Why and how much to document

Why an architecture needs writing down

Every system has an architecture whether or not anyone describes it (see Section 1.1). The architecture description is a separate thing: the documents, diagrams, models and decision records through which people share an understanding of that architecture. In a team of three who sit together and wrote every line, much of the description can live in their heads. As soon as the team grows, people leave, a second team joins, an auditor arrives or the system outlives its authors, knowledge that exists only in heads becomes a risk. Ralph Johnson's definition of architecture as the shared understanding of the expert developers carries a warning: an understanding that is not written down can be shared only by talking, and talking does not scale.

Documenting Software Architectures: Views and Beyond (Paul Clements and colleagues at the Software Engineering Institute, 2nd edition, 2010) names three uses for architecture documentation, and they remain the clearest way to think about why it is worth the effort. It educates: it introduces new team members, external reviewers and new architects to the system. It is the main vehicle for communication among stakeholders: developers, operators, security staff and managers argue about the system through it, and decisions reached in one meeting reach people who were not there. And it is the basis for analysis and construction: it tells implementers what they may and may not do, and it is what an evaluator examines when asking whether the system will meet its quality goals (the evaluation methods of Chapter 11 need a description to work from).

Two consequences follow. First, documentation is a means, not an end: a document that serves none of these uses is waste, however well formatted. Second, the reader decides whether it worked. A description that its author finds complete but that a newcomer cannot use has failed at education, and a diagram the operations team cannot map to real servers has failed at analysis.

Working software over comprehensive documentation

The Agile Manifesto (2001) lists four value pairs, one of which is Working software over comprehensive documentation. It is quoted, often, as permission not to document at all. Read in full, the manifesto says something narrower. Its authors state that while there is value in the items on the right, they value the items on the left more. The value is a priority for when the two compete, not a rejection of documentation.

What the value rejects is the documentation-driven project of the 1990s: hundreds of pages of specifications signed off before code is written, treated as progress in themselves, and abandoned once the code diverges. The word that matters is comprehensive: documentation that tries to describe everything, for its own sake, and is valued more than the running system. Nothing in the manifesto argues against a context diagram, a short record of why the team chose asynchronous messaging, or a runbook that lets the on-call engineer restore service at three in the morning.

Practitioners do disagree about how far to go. Some agile coaches argue that conversation and tests are almost always enough, and that written architecture documentation goes stale faster than it pays back. Others, especially those who maintain long-lived systems or work in regulated sectors, point out that the people who most need the documentation (successors, auditors, the operations team) are exactly those absent from the conversations. Both positions agree on the underlying economics: documentation has a cost to write, a cost to keep current and a cost to read, and it is worth producing only where its value to readers exceeds those costs.

Just enough documentation

Scott Ambler's phrase "just barely good enough" describes the target: a model or document is sufficient when it serves its purpose for its audience, and effort beyond that point costs more than it returns. His point that the audience, not the author, decides whether an artefact is sufficient is the same principle as writing for the reader. George Fairbanks makes the equivalent argument for architecture work as a whole in Just Enough Software Architecture (2010): do as much as the risks justify (see Section 1.8).

Just-enough documentation is therefore not a fixed quantity. It grows with the size and lifetime of the system, the number of teams, the turnover of people, the cost of failure and the demands of regulators. A two-person prototype needs a README and perhaps one diagram. A payments platform run by eight teams under financial regulation needs context, container and deployment views, a decision log going back years, documented security concepts and evidence that the documents are reviewed.

A practical signal is the repeated question. If newcomers ask the same thing in their first week, or the same design argument recurs every few months, the answer belongs in writing. Another is the expensive mistake: if a team broke an unwritten rule ("never call the payment provider from the restaurant app") because nobody told them, the rule was architecture and should have been written down.

What is worth documenting, and what is not

Information differs in two ways that decide how it should be documented. The first is whether it can be recovered from the code. Class names, method signatures and database tables can be read from the source at any time; the reasons a decision was made, the quality goals the system serves and the options that were rejected cannot, because they were never in the code. The second is how often it changes. The system's purpose and its main external partners change rarely; the list of classes in a module changes weekly.

Hand-written architecture documentation should concentrate on what is both important and not recoverable from code: the system's context and scope (who uses it and which other systems it depends on), its quality goals and constraints, the key decisions and their reasons, the coarse-grained structure (the main deployable parts and their responsibilities), the deployment onto infrastructure, the important runtime scenarios, and the cross-cutting concepts that every part must follow, such as how errors are handled, how users are authenticated and how personal data is protected. This list is close to the structure of the arc42 template, covered in Section 4.6.

What is not worth writing by hand is anything the code or the tools already state precisely and that changes often: class diagrams of a whole codebase, lists of endpoints that an OpenAPI file already holds, or descriptions of each function. Where such views are useful, generate them from the source in the build pipeline so they cannot drift. Also omit aspirational content (diagrams of how the system ought to look, presented as if it already did), minutes of meetings whose outcome is captured elsewhere, and duplicated text, which will eventually contradict its copy.

Seven rules for sound documentation

Views and Beyond sets out seven rules for sound documentation. They are worth knowing by heart because almost every documentation failure breaks one of them.

Living documentation and docs-as-code

The traditional failure of architecture documentation is staleness: the description is written at the start, the system changes, and nobody updates the document because it lives somewhere separate from the work. Two related ideas attack this problem at its root.

Docs-as-code, a practice promoted by the Write the Docs community, means treating documentation like source code: written in plain-text formats such as Markdown or AsciiDoc, kept in version control (usually in the same repository as the code it describes), changed through the same pull requests, reviewed by the same people and built and published by the same pipeline. A pull request that changes how orders are dispatched can then be required to update the runtime view in the same commit, and the reviewer sees both.

Living documentation, a term popularised by Cyrille Martraire's book of the same name (2019), goes further: wherever possible, documentation should be derived from the system itself so that it cannot drift. Dependency diagrams generated from the code, API references generated from OpenAPI files, architecture rules checked by automated tests, and diagrams generated from a model kept next to the code are all examples. Hand-written text is reserved for what cannot be derived, chiefly intent and rationale.

Neither idea removes the need for judgement about what to write. Section 4.7, Diagrams as code, covers the tools and habits in detail.