This commit is contained in:
Correl Roush 2020-08-19 23:18:48 -04:00
parent ec26bdaf2b
commit 92a221e75d
3 changed files with 52 additions and 0 deletions

12
20200819222313-adrs.org Normal file
View file

@ -0,0 +1,12 @@
#+title: Architecture Decision Records
#+roam_alias: "ADRs"
ADRs provide documentation on architectural decisions made over the course of
[[file:20200723095845-software_development.org][Software Development]]. Each ADR records a single decision. Different templates
exist for writing them, but generally, they include the context and motivating
factors for the decision, what decision was made, why it was made, and what the
results and implications of that decision are.
* Resources
- [[https://adr.github.io/][ADR GitHub organization]]
-

2
PhilippeKruchten1998.org Normal file
View file

@ -0,0 +1,2 @@
#+TITLE: The decision view's role in software architecture practice
#+ROAM_KEY: cite:PhilippeKruchten1998

View file

@ -0,0 +1,38 @@
#+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.
The whole document should be one or two pages long. We will write each ADR as if
it is a conversation with a future developer. This requires good writing style,
with full sentences organized into paragraphs. Bullets are acceptable only for
visual style, not as an excuse for writing sentence fragments. (Bullets kill
people, even PowerPoint bullets.)
#+end_quote
The suggested writing style is reminiscent of [[file:similarities_and_differences_between_evergreen_note_writing_and_zettelkasten.org][Evergreen note-writing]].