128 lines
6.3 KiB
YAML
128 lines
6.3 KiB
YAML
uuid:
|
|
- value: ec6af399-d960-4715-92c5-760fce33d803
|
|
langcode:
|
|
- value: en
|
|
type:
|
|
- target_id: daily_email
|
|
target_type: node_type
|
|
target_uuid: 8bde1f2f-eef9-4f2d-ae9c-96921f8193d7
|
|
revision_timestamp:
|
|
- value: '2025-05-11T09:00:55+00:00'
|
|
revision_uid:
|
|
- target_type: user
|
|
target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
|
|
revision_log: { }
|
|
status:
|
|
- value: true
|
|
uid:
|
|
- target_type: user
|
|
target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
|
|
title:
|
|
- value: 'ADRs and Technical Design Documents'
|
|
created:
|
|
- value: '2022-09-23T00:00:00+00:00'
|
|
changed:
|
|
- value: '2025-05-11T09:00:55+00:00'
|
|
promote:
|
|
- value: false
|
|
sticky:
|
|
- value: false
|
|
default_langcode:
|
|
- value: true
|
|
revision_translation_affected:
|
|
- value: true
|
|
path:
|
|
- alias: /daily/2022/09/23/adrs-technical-design-documents
|
|
langcode: en
|
|
body:
|
|
- value: |
|
|
<h2 id="architectural-decision-records">Architectural Decision Records</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>They usually consist of the sections:</p>
|
|
|
|
<ul>
|
|
<li>Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?</li>
|
|
<li>Context - what is the issue that is causing the decision or change?</li>
|
|
<li>Decision - what is the change that's being done or proposed?</li>
|
|
<li>Consequences - what becomes easier or more difficult to do?</li>
|
|
</ul>
|
|
|
|
<p>Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.</p>
|
|
|
|
<p>These will remain in place to form a decision log, with specific ADRs being marked as superseded if a newer ADR replaces it.</p>
|
|
|
|
<h2 id="technical-design-documents">Technical Design Documents</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The first heading is always "What problem are we trying to solve?", or sometimes just "The problem".</p>
|
|
|
|
<p>Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.</p>
|
|
|
|
<p>Unlike ADRs, there are no other set headings but these are some suggested ones:</p>
|
|
|
|
<ul>
|
|
<li>What is the current process?</li>
|
|
<li>What are any requirements?</li>
|
|
<li>How do we solve this problem?</li>
|
|
<li>Alternative approaches</li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><a href="https://adr.github.io">Find our more about ADRs</a> or <a href="https://altf4.wiki/t/how-do-i-write-a-tdd/21">find out more about TDDs</a>.</p>
|
|
|
|
|
|
format: full_html
|
|
processed: |
|
|
<h2 id="architectural-decision-records">Architectural Decision Records</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>They usually consist of the sections:</p>
|
|
|
|
<ul>
|
|
<li>Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?</li>
|
|
<li>Context - what is the issue that is causing the decision or change?</li>
|
|
<li>Decision - what is the change that's being done or proposed?</li>
|
|
<li>Consequences - what becomes easier or more difficult to do?</li>
|
|
</ul>
|
|
|
|
<p>Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.</p>
|
|
|
|
<p>These will remain in place to form a decision log, with specific ADRs being marked as superseded if a newer ADR replaces it.</p>
|
|
|
|
<h2 id="technical-design-documents">Technical Design Documents</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The first heading is always "What problem are we trying to solve?", or sometimes just "The problem".</p>
|
|
|
|
<p>Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.</p>
|
|
|
|
<p>Unlike ADRs, there are no other set headings but these are some suggested ones:</p>
|
|
|
|
<ul>
|
|
<li>What is the current process?</li>
|
|
<li>What are any requirements?</li>
|
|
<li>How do we solve this problem?</li>
|
|
<li>Alternative approaches</li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><a href="https://adr.github.io">Find our more about ADRs</a> or <a href="https://altf4.wiki/t/how-do-i-write-a-tdd/21">find out more about TDDs</a>.</p>
|
|
|
|
|
|
summary: null
|
|
field_daily_email_cta: { }
|