Skip to content
Software Architecture Guide

arc42 Introduction and Goals

Explanation

Section titled “Explanation”

Section 1 of arc42 (see the article arc42 Architecture Documentation Template) is the entry point. It describes the requirements and driving forces that architects and the development team must consider.

What goes into it

  • A short requirements overview. Keep it brief. If requirements documents already exist, point to them instead of copying them.
  • Quality goals. These are the most important qualities the architecture must deliver. Limit them to the top three, at most five.
  • A stakeholder table. A stakeholder is anyone with an interest in the system. The table lists roles, person names, and what each expects from the architecture and its documentation.

Quality goals need scenarios

A keyword such as “performance” or “security” says little. Add a brief scenario that shows what the goal means in practice. Generic keywords alone are a common pitfall.

Details live elsewhere

Section 1 holds only the top goals. Complete and detailed quality requirements belong in section 10. See the article arc42 Quality Requirements Chapter for that part.

Example

Section titled “Example”

A team documents a tool that checks websites for broken links. In section 1 they list quality goals in priority order:

  1. Correctness: every broken internal link is found.
  2. Safety: the tool never changes the files it checks.
  3. Performance: checks run fast enough for regular use.

Each goal gets a short scenario. The stakeholder table lists the website authors, who expect reliable reports, and the developers, who expect clear documentation. The requirements overview is a few lines with a link to the full requirements document.

Trade-offs

Section titled “Trade-offs”

A short section is easy to read, but it leaves out detail. Readers who need the full picture must follow links to the requirements documents and to section 10. Limiting the goals to three to five forces priorities, so some qualities will not appear here.

Checks

Section titled “Checks”
  • Section 1 lists at most five quality goals.
  • Each quality goal has a brief scenario, not just a keyword.
  • The stakeholder table gives roles, names and expectations.
  • The requirements overview is short and links to existing requirements documents.
  • Detailed quality requirements are deferred to section 10.
Section titled “Related”

Sources

Section titled “Sources”