Listing Vault SE322 · chapter 09 · Architecture Documentation

Chapter 09 — Architecture Documentation

The documentation rules, what belongs in a view, the established view approaches, what lives beyond views, and how documentation stays alive.

09chapter
—lists
—total items
09

Architecture Documentation

10 lists

Documentation Principles 7

  1. Write from the reader's point of view
  2. Avoid unnecessary repetition — one source of truth per fact
  3. Avoid ambiguity; define the notation
  4. Use a standard organization and provide a roadmap
  5. Record rationale
  6. Keep documentation current
  7. Review documentation for fitness with its intended readers

What Belongs in a View 5

  1. Primary presentation — usually a diagram plus key annotations
  2. Element catalog — responsibilities, interfaces and relationships
  3. Context diagram — the view boundary and external dependencies
  4. Variability guide — where options exist and their permitted values
  5. Rationale — why the view looks this way and what was rejected

Variability Binding Times 3

  1. Configurable
  2. Build-time choice
  3. Run-time setting

Established View Approaches 6 + 1

  1. Kruchten 4+1
  2. Siemens Four-Views
  3. Herzum and Sims
  4. Software Cost Reduction (SCR)
  5. RUP
  6. SEI Views and Beyond
  7. C4 — a widely used modern variant

Siemens Four Views 4

  1. Conceptual
  2. Module
  3. Execution
  4. Code

C4 Levels 4

  1. Context
  2. Container
  3. Component
  4. Code

A Complete Documentation Package 7

  1. Documentation roadmap — which part answers which question
  2. The view documents themselves
  3. System overview
  4. Rationale and decisions (ADRs)
  5. Directory / index
  6. Glossary
  7. Acronym list

Cross-Cutting Concerns 6

Belong to no single view but constrain all of them.

  1. Interfaces
  2. Data
  3. Security
  4. Error handling
  5. Deployment
  6. Build concerns

Diagram Quality Rules 5

  1. Every diagram needs a key defining shapes, line styles and colors
  2. Boxes and lines are ambiguous without defined semantics
  3. Show only what is relevant to the view and audience
  4. One diagram should answer one question
  5. Automated diagrams help freshness but still need curation

Living Documentation 5

  1. Version documentation with the code where appropriate
  2. Review for drift and link decisions to implementation evidence
  3. Make documentation part of the definition of done
  4. Generate what changes most often — API references, dependency graphs, topologies
  5. Concise enough to maintain, detailed enough to act on