2021-07-29 22:51:04 +00:00
|
|
|
:PROPERTIES:
|
|
|
|
|
:ID: b7c89b7b-5d3a-4cd9-9d26-8107b32ba5a0
|
|
|
|
|
:ROAM_REFS: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
|
|
|
|
|
:END:
|
2020-08-20 03:18:48 +00:00
|
|
|
#+title: Documenting Architecture Decisions
|
2021-07-29 22:51:04 +00:00
|
|
|
#+filetags: :literature:articles:
|
2020-08-20 03:18:48 +00:00
|
|
|
|
|
|
|
|
Michael Nygard describes a method for tracking "architecturally significant
|
2021-07-29 22:51:04 +00:00
|
|
|
decisions" in lightweight [[id:bfb4cd68-85ec-4ea7-99b1-247c918e87bb][ADRs]] using a concise template:
|
2020-08-20 03:18:48 +00:00
|
|
|
|
|
|
|
|
#+begin_quote
|
|
|
|
|
- Title :: These documents have names that are short noun phrases. For example,
|
|
|
|
|
"ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant
|
|
|
|
|
Integration"
|
|
|
|
|
|
|
|
|
|
- Context :: This section describes the forces at play, including technological,
|
|
|
|
|
political, social, and project local. These forces are probably in tension,
|
|
|
|
|
and should be called out as such. The language in this section is
|
|
|
|
|
value-neutral. It is simply describing facts.
|
|
|
|
|
|
|
|
|
|
- Decision :: This section describes our response to these forces. It is stated
|
|
|
|
|
in full sentences, with active voice. "We will ..."
|
|
|
|
|
|
|
|
|
|
- Status :: A decision may be "proposed" if the project stakeholders haven't
|
|
|
|
|
agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or
|
|
|
|
|
reverses a decision, it may be marked as "deprecated" or "superseded" with a
|
|
|
|
|
reference to its replacement.
|
|
|
|
|
|
|
|
|
|
- Consequences :: This section describes the resulting context, after applying
|
|
|
|
|
the decision. All consequences should be listed here, not just the "positive"
|
|
|
|
|
ones. A particular decision may have positive, negative, and neutral
|
|
|
|
|
consequences, but all of them affect the team and project in the future.
|
|
|
|
|
|
2021-07-29 22:51:04 +00:00
|
|
|
The whole document should be one or two pages long. We will write each ADR [[id:b3bb163c-4f36-4060-bf9d-47a478914b5b][as if
|
2020-08-21 02:18:52 +00:00
|
|
|
it is a conversation]] with a future developer. This requires good writing style,
|
2021-07-29 22:51:04 +00:00
|
|
|
with [[id:dd4a78ca-e525-47be-bb13-5b54b2397957][full sentences]] organized into paragraphs. Bullets are acceptable only for
|
2020-08-20 03:18:48 +00:00
|
|
|
visual style, not as an excuse for writing sentence fragments. (Bullets kill
|
|
|
|
|
people, even PowerPoint bullets.)
|
|
|
|
|
#+end_quote
|
