"value":"\n <h2 id=\"architectural-decision-records\">Architectural Decision Records<\/h2>\n\n<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>\n\n<p>They usually consist of the sections:<\/p>\n\n<ul>\n<li>Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?<\/li>\n<li>Context - what is the issue that is causing the decision or change?<\/li>\n<li>Decision - what is the change that's being done or proposed?<\/li>\n<li>Consequences - what becomes easier or more difficult to do?<\/li>\n<\/ul>\n\n<p>Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.<\/p>\n\n<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>\n\n<h2 id=\"technical-design-documents\">Technical Design Documents<\/h2>\n\n<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>\n\n<p>The first heading is always \"What problem are we trying to solve?\", or sometimes just \"The problem\".<\/p>\n\n<p>Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.<\/p>\n\n<p>Unlike ADRs, there are no other set headings but these are some suggested ones:<\/p>\n\n<ul>\n<li>What is the current process?<\/li>\n<li>What are any requirements?<\/li>\n<li>How do we solve this problem?<\/li>\n<li>Alternative approaches<\/li>\n<\/ul>\n\n<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>\n\n<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>\n\n<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>\n\n<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>\n\n ",
"format":"full_html",
"processed":"\n <h2 id=\"architectural-decision-records\">Architectural Decision Records<\/h2>\n\n<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>\n\n<p>They usually consist of the sections:<\/p>\n\n<ul>\n<li>Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?<\/li>\n<li>Context - what is the issue that is causing the decision or change?<\/li>\n<li>Decision - what is the change that's being done or proposed?<\/li>\n<li>Consequences - what becomes easier or more difficult to do?<\/li>\n<\/ul>\n\n<p>Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.<\/p>\n\n<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>\n\n<h2 id=\"technical-design-documents\">Technical Design Documents<\/h2>\n\n<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>\n\n<p>The first heading is always \"What problem are we trying to solve?\", or sometimes just \"The problem\".<\/p>\n\n<p>Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.<\/p>\n\n<p>Unlike ADRs, there are no other set headings but these are some suggested ones:<\/p>\n\n<ul>\n<li>What is the current process?<\/li>\n<li>What are any requirements?<\/li>\n<li>How do we solve this problem?<\/li>\n<li>Alternative approaches<\/li>\n<\/ul>\n\n<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>\n\n<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>\n\n<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>\n\n<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>\n\n ",
