Skip to content
Software Architecture Guide

Characteristics of a Good View

Explanation

Section titled “Explanation”

A view shows how the architecture addresses the concerns of certain stakeholders. A stakeholder is anyone with an interest in the system. See the articles Architecture View and Stakeholder. A good view lets those people check whether their concerns are covered.

Start with the reader. Ask your own stakeholders which artifacts or information they expect from the documentation. General guidance only gives rough approximations, because the right content depends on your stakeholders. To start the conversation, show them examples of what you could deliver with low effort.

Name the audience. A viewpoint is a reusable set of conventions for one type of view. It also names the stakeholders that this type of view serves. So you can judge a view by asking who it is for and what it should tell them.

Match detail to demand. Deeper levels of a building block view cost a lot to create and maintain. Create them only where real demand for the information exists. Building blocks are refined step by step, from level 1 down to the detail that is appropriate.

Make each diagram readable on its own. C4 gives these tips:

  • Give each diagram a title that states its type and scope.
  • Make it understandable without a separate narrative.
  • Use acronyms that every audience understands.
  • Keep notation, such as color coding, consistent within and across diagrams.

Review with questions. C4 offers a checklist. It asks, for example, whether the scope is clear and whether every element has a name.

Example

Section titled “Example”

A team documents an online shop. The support manager says she needs to know which parts handle orders. The team shows her a rough one-page sketch of the main building blocks. She confirms it answers her question. The team then adds deeper detail only for the order part, where people have asked for it. Each diagram has a title with its type and scope.

Trade-offs

Section titled “Trade-offs”

Deeper detail costs effort to create and maintain, so adding it everywhere wastes time. The facts here do not say how much detail is too much, so ask your stakeholders. Standalone diagrams may need more labels, and a stakeholder’s needs can differ from general guidance.

Checks

Section titled “Checks”
  • The documentation records which stakeholders were asked what information they expect.
  • Each view or viewpoint names the stakeholders it serves and the concerns it addresses.
  • Deeper levels of the building block view exist only where there is real demand for them.
  • Each diagram has a title stating its type and scope, and it can be mostly understood without a narrative.
  • Notation such as color coding is consistent within and across diagrams, and every element has a name.
Section titled “Related”

Sources

Section titled “Sources”