What & How: practical, pragmatic approach to documenting architecture.

  1. Intro & Goals
    1. motivation/business problems solved, e.g. tabulated use cases
    2. 3~5 “quality goals” e.g. reliability/security/maintainability/performance/compatibility
    3. stakeholders (target audience/users)
  2. Constraints: inappropriate use cases, e.g. “unsupported on Windows”
  3. Context & Scope diagram
    1. business/domain perspective: diagrams showing relation to other tools/systems
    2. (optional) technical perspective: UML unified modelling language
  4. Solution Strategy: tech stack, design pattern
  5. Code (architecture “building blocks”) Diagrams
    1. whitebox: overall API
    2. blackboxes: subcomponents
  6. Runtime Diagram: list of steps, flowchart, sequence diagram
  7. Deployment Diagram
    1. hardware/infrastructure requirements
    2. mapping of software building blocks to said hardware
  8. Pervading Ethos: design patterns, UX user experience
         choices, approach to security, “under-the-hood” concepts
  9. Architecture Decisions: rationale for not doing things differently, e.g. ADR architecture decision record
         (worth its own TL;DR too long; didn’t read
         :scroll:)
    • :thinking: (personal opinion) ADR seems an XY problem attempted solution (Y) misses the original problem (X)
             . The motivation for ADR (i.e. not just knowing the decision – reading source code – but remembering motivation behind it) can be easily be addressed by inline code comments with URLs (e.g. linking to a GitHub comment) and/or commit messages. The only real value of ADR is collating such comments.
  10. Detailed Quality Goals
    1. more detailed than (1.2) above, e.g. ATAM “quality attribute utility tree”
    2. usage scenarios, e.g. “processes user input within 1 second” (not to be confused with use cases)
  11. Risks & Tech Debt: current issues & tips to manage/reduce/avoid them
  12. Glossary: domain/technical terms; avoid synonyms & homonyms to maximise identical understanding