45 lines
2.4 KiB
Markdown
45 lines
2.4 KiB
Markdown
---
|
|
title: "ADRs and Technical Design Documents"
|
|
pubDate: 2022-09-23
|
|
permalink: "archive/2022/09/23/adrs-technical-design-documents"
|
|
tags: []
|
|
---
|
|
|
|
## 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](https://adr.github.io) or [find out more about TDDs](https://altf4.wiki/t/how-do-i-write-a-tdd/21).
|