Skip to content
Documentation

Documentation someone will actually trust

A document that was true once and is wrong now is worse than no document, because someone will act on it. What gets written, and by whom, depends on the level.

What this covers

The documents worth having

Architecture

What the system is made of and how the parts relate, at a level of detail that survives the next three months.

Infrastructure and delivery

Where it runs, how a change reaches production, and what to do when that goes wrong at two in the morning.

Decisions and why

The reasoning behind the choices, which is the part that is always lost and always needed later.

Onboarding

What a new developer or a new agent needs to know before touching anything.

Who writes it

The honest answer depends on the level

  1. Advisory level

    I read and comment on documents, explain what should be in them, and give you the prompt or the brief to produce them. I do not write your project documentation as a deliverable.

  2. Leadership level

    I require documentation from the team, set the task for it and accept the result. I am not the one producing it instead of them.

  3. Vibe Coding level

    Documentation is part of delivery. Code, infrastructure and important decisions are written down as the work happens.

  4. Why the difference matters

    Advertising documentation as a deliverable on every level would be selling you something the price does not contain.

What to expect

Do not expect

A hundred-page document produced once and never updated

Documentation of a system I have not read

Written deliverables on the advisory level

Expect

Documents short enough that someone reads them

Claims that can be checked against the running system

Decisions recorded with the reasoning, not just the outcome

On the top level, documentation shipped with the work

Start with the area that worries you most

Pick the level of involvement that fits, describe your product, and we begin there.