ADRs and Technical Design Documents
Architectural Decision Records
Architectural Decision Records (ADRs) are documents to record software design choices. They could be saved in your code repository as plain-text or Markdown files, or stored in Confluence or a wiki - wherever your team stores its documentation.
They usually consist of the sections:
- Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?
- Context - what is the issue that is causing the decision or change?
- Decision - what is the change that's being done or proposed?
- Consequences - what becomes easier or more difficult to do?
Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.
These will remain in place to form a decision log, with specific ADRs being marked as superseded if a newer ADR replaces it.
Technical Design Documents
A similar type of document are Technical Design Documents (TDDs), that I first saw on TheAltF4Stream. I like to think of these as lightweight ADRs.
The first heading is always "What problem are we trying to solve?", or sometimes just "The problem".
Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.
Unlike ADRs, there are no other set headings but these are some suggested ones:
- What is the current process?
- What are any requirements?
- How do we solve this problem?
- Alternative approaches
I like after describing the problem, being able to move straight into describing what's appropriate and relevant for this task and ignore sections that aren't needed.
When I started writing ADRs, they all had the 'Accepted' status as I was either writing them for myself or in a pair or mob. As wasn't adding any value, I've removed it since switching to writing TDDs.
Whether you use ADRs, TDDs or another approach, it's very useful to have a log of all of your architectural design decisions, both looking back in the future to remember why something was done in a certain way, or before you start implementing a solution to review the problem, evaluate the requirements and all potential solutions and document the selected one any why it was selected.
Find our more about ADRs or find out more about TDDs.
- Oliver
