notes
This commit is contained in:
parent
ec26bdaf2b
commit
92a221e75d
3 changed files with 52 additions and 0 deletions
12
20200819222313-adrs.org
Normal file
12
20200819222313-adrs.org
Normal 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
2
PhilippeKruchten1998.org
Normal file
|
@ -0,0 +1,2 @@
|
|||
#+TITLE: The decision view's role in software architecture practice
|
||||
#+ROAM_KEY: cite:PhilippeKruchten1998
|
38
blog_documenting_architecture_decisions_relevance.org
Normal file
38
blog_documenting_architecture_decisions_relevance.org
Normal 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]].
|
Loading…
Reference in a new issue