Skip to content
Documentation

Documentation that matches reality

Documentation written from memory is wrong within a month and everyone learns to distrust it. Documentation generated from the code, with evidence, is worth keeping.

What is in this category

Documents with a job to do

Each one exists to answer a question someone will actually ask.

C4 documentation

Context, container and component views, each derived from the code and each traceable back to it.

Architecture decision records

Why the system is the way it is: the decision, the alternatives, and what it cost. The document that saves the next person a month.

Sequence diagrams

The flows that matter, drawn as they actually execute, including the error paths people forget to document.

Deployment runbooks

What to do to release, and what to do when the release goes wrong — written to be followed by someone tired and alone.

Interface registry

Every API and integration point, what it promises, who depends on it and what breaks if it changes.

Operational documentation

Where things run, what to check when they misbehave, and which alarms mean something.

How documentation work runs

  1. Generated from the system, not from memory

    The procedure reads the code first. Anything it cannot find, it marks as unknown rather than inventing.

  2. Every claim carries its source

    A diagram element that cannot be traced to a file is a drawing, not documentation.

  3. Gaps are stated, not filled

    Where the system is genuinely unclear, the document says so. That is more useful than a confident guess and safer to act on.

  4. Reviewable by a person

    Documentation is one of the best things to send for expert review: mistakes in it are cheap to fix and expensive to leave.

When to invest in documentation

Can wait if

The product may not exist in three months

One person builds and operates all of it

The architecture is still changing weekly

Do it now if

You are onboarding developers or a vendor

A customer or investor is doing due diligence

The only person who understood it is leaving

You are about to let an AI agent refactor it

Pick the category that matches your worry

Describe the situation in your own words and see the procedure — and its cost — before you spend anything.