2020-08-20 03:18:48 +00:00
|
|
|
#+title: Documenting Architecture Decisions
|
|
|
|
|
#+roam_key: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
|
|
|
|
|
#+roam_tags: literature articles
|
|
|
|
|
|
|
|
|
|
Michael Nygard describes a method for tracking "architecturally significant
|
|
|
|
|
decisions" in lightweight [[file:20200819222313-adrs.org][ADRs]] using a concise template:
|
|
|
|
|
|
|
|
|
|
#+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.
|
|
|
|
|
|
2020-08-21 02:18:52 +00:00
|
|
|
The whole document should be one or two pages long. We will write each ADR [[file:20200820215950-write_conversationally.org][as if
|
|
|
|
|
it is a conversation]] with a future developer. This requires good writing style,
|
|
|
|
|
with [[file:20200820215905-write_in_full_sentences.org][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
|
