100 lines
No EOL
7.3 KiB
JSON
100 lines
No EOL
7.3 KiB
JSON
{
|
|
"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": "\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 ",
|
|
"summary": null
|
|
}
|
|
],
|
|
"feeds_item": [
|
|
{
|
|
"imported": "1970-01-01T00:33:45+00:00",
|
|
"guid": null,
|
|
"hash": "ce0fd785eeded51305f4d32749a7ce65",
|
|
"target_type": "feeds_feed",
|
|
"target_uuid": "90c85284-7ca8-4074-9178-97ff8384fe76"
|
|
}
|
|
]
|
|
} |