notes

20200819222313-adrs.org

@@ -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]]
+-

PhilippeKruchten1998.org

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

blog_documenting_architecture_decisions_relevance.org

@@ -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]].