Architecture Viewpoint

The reason most architecture documentation fails is that it attempts one diagram for all readers, and therefore serves none. Different stakeholders have different questions, and each needs its own view.

The common set: a functional or logical view of components and responsibilities; a deployment view of what runs where; an information view of data ownership, flow and lifecycle; a development view of code structure and module boundaries; an operational view of monitoring, backup and support; and a security view of trust boundaries and controls.

The practical instruction that follows: know the audience before drawing. A diagram for an executive, a new engineer, an operations team and a security reviewer are four different artefacts, and combining them produces something with too much detail for the first and too little for the last.

What keeps views useful over time: a consistent level of abstraction within each one (the most common defect is mixing a business capability and a database table on the same diagram); generation from source where possible; and honesty about what is current versus intended, clearly labelled, since a diagram of an aspiration presented as fact misleads exactly the people who most need it to be right.