From ac54cda1a6f50e18283baac6019329279029392f Mon Sep 17 00:00:00 2001 From: Oliver Davies Date: Sun, 25 Sep 2022 00:21:13 +0100 Subject: [PATCH] fix(daily-email): add content --- website/source/_daily_emails/2022-09-23.md | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/website/source/_daily_emails/2022-09-23.md b/website/source/_daily_emails/2022-09-23.md index 3c5edb54..d3bb879f 100644 --- a/website/source/_daily_emails/2022-09-23.md +++ b/website/source/_daily_emails/2022-09-23.md @@ -5,3 +5,40 @@ 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).