Documentation Architecture

A good documentation site is not "all the documents we could write." It is the smallest set of document types that lets each audience do its job — and a clear rule for where each new document belongs. This guide defines the document types, the two axes that separate the easily-confused ones, and a flexible model for choosing only the types your project actually needs.

1. The documentation goal

Documentation exists to let specific people answer specific questions without interrupting someone else. Four jobs cover almost everything:

Job The reader is trying to…

Onboard

understand what the system is and how it is built, well enough to contribute.

Operate

run the system and produce outcomes with it, day to day and when it breaks.

Decide

understand why the system is shaped the way it is, before changing it.

Audit

trace a behaviour, contract, or decision back to its source of truth.

Every document type below earns its place by serving one or more of these jobs for a defined reader. A document that serves no identified reader is waste — it costs maintenance and dilutes the rest. This is the core of the flexible approach: types are added when a reader needs them, not by default.

2. The document-type catalogue

Each type answers one question for one primary audience. In an Antora site each maps to a module; the canonical per-type guide (where one exists) defines its internal page structure.

Type Answers Audience Per-type guide

Requirements / Use cases

What must the system do?

Analyst, developer

Requirements Guide

Design

How is a feature built?

Developer, architect

Design Guide

Architecture / ADR

Why is the system shaped this way?

Architect, lead

Architecture & ADR Guide

Reference (API, schema, config)

What are the exact contracts?

Integrator, developer

(project-specific; often generated)

Operations

How do we keep the system healthy?

Engineer, SRE

Operations Guide

Runbooks

How do we recover when it breaks?

Engineer, SRE

Runbooks Guide

Operational Procedures (SOPs)

How does a staff member produce a standard outcome?

Operator, staff

Procedures Guide

User Guide

How do I learn to use it?

Operator, end-user

User Guide Authoring

3. The two axes

The engineering types (requirements, design, architecture, reference) are rarely confused — they sort themselves by their question. The operational types are where teams put documents in the wrong place, because "operations" feels like one bucket. It is two, separated by two axes. Ask them in order:

Axis Question

Audience

Who reads this — an engineer keeping the system alive, or a staff member / operator doing their job through the system?

Nature

Is it recurring (runs on a cadence or on demand) or exceptional (a one-off incident or correction)? And is it prescriptive (numbered steps) or descriptive (explanation and examples)?

The audience axis is the one most often missed, and it is decisive.

3.1. The operational quadrant

Recurring / steady-state Exceptional / one-off

Technical (engineer / SRE)

Operations
keep the system healthy: cache, observability, config, mail

Runbooks
surgical recovery & data correction: restores, reconciliations

Business (operator / staff)

Operational Procedures
produce a standard outcome: imports, inventory lifecycle, reporting

(rare — fold the one-off into a procedure; if it is truly an incident it is a Runbook)

Orthogonal to the quadrant sits the learning material — the User Guide: descriptive explanations and worked examples for staff learning a feature. A user guide teaches understanding; a procedure gives the steps. They cross-link, they do not duplicate.

A procedure is defined by the outcome it produces, not the tool it uses. A report produced by SQL today and by a UI tomorrow is the same procedure — it stays in Procedures either way. Don’t file by mechanism.

4. One feature, a family of documents

A single capability usually produces a family of documents across types, each for a different reader, cross-linked rather than merged:

  Feature "Season Leaderboard"
    ├── Requirement   — what standings must be produced            (analyst/dev)
    ├── Design        — the schema and how results are classified  (dev/architect)
    ├── ADR           — why we chose this scoring model            (architect)
    ├── Procedure     — how an operator configures a league        (operator)
    └── User Guide    — how a staff member reads the standings     (end-user)

This is expected and healthy. The failure mode is the opposite — one document trying to serve every reader, so it serves none well. Let each type stay in its lane and link across.

5. Choosing the types your project needs

Not every project needs every type. Choose by project goal — what the project is and who consumes it. Start from a profile, then add or drop a type only when a real reader appears or disappears.

Project kind Typically needs Typically omits

Shared library / SDK

Architecture, Design, API Reference, ADRs

Procedures, User Guides, Runbooks

Internal microservice

Requirements, Design, Architecture, Operations, Runbooks

User Guides (Procedures only if operators drive it)

Operator-facing product

The full set — Requirements, Design, Operations, Runbooks, Procedures, User Guides

—

Ops / automation tool

Runbooks, Procedures, Operations

Requirements (light), User Guides

Data / integration pipeline

Design, Reference (schemas), Operations, Runbooks

User Guides, Procedures

An empty or stub module is worse than an absent one. It implies coverage that isn’t there and costs the reader a click to discover nothing. Create a type’s module when you have the first real document for it — not in anticipation. Adding a module later is cheap (see Antora Configuration Guide).

5.1. The decision flow

When a new document lands on your desk:

  1. Is it specific to one codebase and meaningless elsewhere? → that project’s own docs. Otherwise it is solution-wide.

  2. Does it state what the system must do, how it is designed, or why? → Requirements / Design / Architecture.

  3. Is it operational? Then apply the two axes:

    1. Who runs it? Engineer keeping the system alive → Operations (steady-state) or Runbooks (exceptional). Operator producing a business outcome → Procedures.

    2. Is it teaching rather than instructing? → User Guide.

  4. Does the type’s module exist yet? If not, and this is the first real document for it, create it now (see the per-type guide). If the document would be the only thing in a type for the foreseeable future, consider folding it into an adjacent type instead.

6. Putting it in the site

In Antora, each type is a module under the component, with its own nav.adoc and an index.adoc that states the module’s purpose and the boundary with its neighbours (e.g. an Operations index that points at Procedures for business outcomes). Group the modules in the component navigation by intent — typically Requirements & Design, Architecture, Build & Operate (Operations + Runbooks), and User Enablement (Procedures + User Guides) — so the navigation itself signals "engineers start here, operators start there."

See Antora Configuration Guide for module mechanics and Getting Started for choosing your profile at project init. Each type’s internal structure is defined by its per-type guide, linked in the catalogue above.

7. Reference implementation

The Event & Membership System (EMS) documentation applies this model end-to-end across both engineering and operations: Requirements/Use-cases, Architecture, Design (common-design), Operations, Runbooks, Procedures, and User Guide modules, with a project-level documentation-structure.adoc page that instantiates this architecture for that codebase. It is the worked example of the full operator-facing profile.