Skip to content
Software Architecture Guide

Software Architecture Documentation Consensus

Explanation

Section titled “Explanation”

Many approaches to documenting architecture now share one core idea. The architecture description is not one large document. It is split into several views that relate to each other.

Views are the central element. A view shows structural aspects of an architecture. It includes only the elements that matter to stakeholder concerns. (See Architecture View and Concern.)

Why not one big document? A single monolithic description is hard to keep sound. Because of its complexity, it tends to be incomplete, wrong or outdated. Views avoid this by splitting the content into smaller pieces.

Views serve stakeholders. A view can target one class of stakeholders, or even one person. It should address the concerns of one or more stakeholders. (See Stakeholder.)

Diagrams help build views. C4 is one example. It is a developer-friendly, diagram-oriented approach. It uses a small set of abstractions and diagram types, so it is easy to learn. The abstractions form a hierarchy:

  • A system contains containers (applications and data stores).
  • Containers contain components.
  • Code elements implement the components.

Templates organize the documentation. arc42 arranges documentation in twelve sections. These include a Building Block View (section 5) and a Runtime View (section 6). It also recommends always documenting some essential information about your system, even in agile contexts.

Views are the core. Diagrams help create them. Stakeholder concerns decide what each view contains.

Example

Section titled “Example”

A team builds an online shop. Instead of one long document, it writes short views. One view is for managers and shows the shop and the systems around it. Another is for developers and shows the parts inside the shop. Each view has a clear audience and stays small, so it is easier to keep current.

Trade-offs

Section titled “Trade-offs”

Splitting the description into views avoids the problems of a monolithic document. The price is that you must keep several interrelated views consistent with each other. Small approaches such as C4 are easy to learn, but they offer only a few abstractions and diagram types. A fuller template such as arc42 asks for more sections to fill in.

An architecture description made of several views, each shaped by stakeholder concerns.

Diagram source 
flowchart TD
  S[Stakeholder concerns] --> V1[View: context]
  S --> V2[View: building blocks]
  S --> V3[View: runtime]
  V1 --> D[Architecture description]
  V2 --> D
  V3 --> D

Checks

Section titled “Checks”
  • The architecture description is split into several interrelated views, not one monolithic document.
  • Each view states which stakeholders and concerns it addresses.
  • If C4 is used, the diagrams follow the hierarchy of system, container, component and code element.
  • If arc42 is used, the Building Block View and Runtime View sections are present.
Section titled “Related”

Sources

Section titled “Sources”