Since lesson 4.1.1 you have been writing documentation: an inventory, quality goals, ADRs, a C4 model, contexts, a threat model, a permissions table, a cost calculation, disaster drills. Each piece came into being in its lesson and was right there. Meanwhile the code underneath has moved: modules were added, grains, tenants, stamps. In this lesson the pieces become documentation that is correct, that can be read in a set amount of time, and that does not go stale again without anyone noticing.
The bar has been fixed since the outline of this module: A stranger reads 30 minutes in docs/ and can afterward explain how a
quote runs through the system. It is checked in lesson 4.9.6 by a person from your circle, and in 4.9.7
you read the same pages with the checklist of the architecture review.
Whom you write for
Architecture documentation has several readers, and each wants something different:
| Who | Wants to know | Reads first |
|---|---|---|
| a new developer on the team | where things are, how a flow runs through the modules, which rules apply | entry page, containers, components, the path of a quote |
| the architecture review in 4.9.7 | why it is built this way and what it costs | ADRs, quality scenarios with proof, cost |
| operations | what runs where, what to do in an emergency | deployment, disaster recovery plan and drills, permissions table |
| security | where the boundaries are and what they protect | trust boundaries, threat model, permissions table |
| the domain expert | whether the system models their processes correctly | context, glossary, contexts |
You do not write five documentations, but one with five ways in. The ways are on the entry page, docs/README.md. Microsoft's
guidance for architects calls this bundle a design specification (architecture design specification): diagrams,
decisions, nonfunctional requirements, disaster recovery plan, security, all with a status and cross-references. The Kladde already has all of it,
scattered. Now it gets an order.