Three reports every operations director should have on Monday morning

Most software documentation rots because of how it is treated by the team that wrote it. It is a deliverable: produced at the end of a project, signed off, and never opened again. Six months later it is wrong. Twelve months later it is wrong about something dangerous.

The fix is not better writers, more pages, or a Confluence subscription. The fix is to treat documentation as a feature of the system, with the same care as any other feature. That means it has an owner, it has tests, it gets updated as part of changes, and it breaks the build when it is wrong.

Why documentation rots

Three causes, in order of frequency:

1. Documentation lives in a separate place to the code

The code is in a Git repository. The documentation is in a Confluence space. They cannot be reviewed together. A pull request changes the code; the documentation is supposed to be updated, but there is no enforcement. The reviewer does not see the doc. Six months later the documentation describes a behaviour that no longer exists.

2. Documentation has no owner

The deliverable was written by whoever was free in the last week of the project. They are now on a different project. The original team has been disbanded. When the doc gets a comment saying “this is wrong”, nobody knows whose job it is to fix it.

3. Documentation has no tests

If the README says “run npm install && npm start to start the dev server”, and that command no longer works, nothing complains. The CI suite does not run that example. The doc is wrong, the readers cannot work, the team apologises and quietly fixes it once a year.

Documentation as a feature

If documentation is a feature, it inherits four things automatically:

1. It lives next to the code

The README is in the repo. The architecture document is in the repo. The runbook is in the repo. The deployment plan is in the repo. The acceptance test for “does this run on a fresh machine” is in the repo, and it includes the steps from the README.

This is mundane and worth doing. A pull request that changes behaviour shows up in the same diff as the documentation update. The reviewer notices when one is missing.

2. It has an owner

Each document file has a maintainer in its frontmatter or its top comment. When the maintainer leaves, the project lead reassigns. When somebody opens an issue against the doc, the maintainer is notified, not a generic team mailbox.

3. It is tested

The README’s installation steps are run by CI on a fresh container, every week. The architecture diagram references components that genuinely exist; the script that generates the diagram fails the build if a referenced component has been renamed. The runbook’s recovery procedure is run as a drill quarterly.

None of these are exotic. They are fifteen-line shell scripts.

4. It gets shipped

If you do not ship documentation, nobody knows what it says. The team’s public site, the customer onboarding pack and the training material all derive from the same source files. When the source changes, the derivatives regenerate.

What good looks like

A small system that takes documentation seriously typically has five files at the root of the repository:

1. README.md. What the project is, who it is for, how to run it on a fresh machine. Owner named.
2. ARCHITECTURE.md. The shape of the system, the major components, the trade-offs that have been made. Updated when those trade-offs change.
3. RUNBOOK.md. What to do when something breaks. Numbered procedures, with screenshots of the relevant dashboards.
4. SECURITY.md. Threat model, response process, security contact.
5. CHANGELOG.md. A human-readable history of what has changed and when.

Each one has a maintainer. Each one has at least one CI test that breaks the build if it is wrong about something material.

The cost

This costs almost nothing in time. It costs about an hour to set up the structure. It costs ten minutes per pull request to update. It costs nothing to maintain because the maintenance is part of the work, not on top of it.

What it saves is incalculable. It saves the next person to inherit the system from a six-week onboarding period of confusion. It saves the on-call engineer at 3am from guessing. It saves the customer from being told “we’ll have to look into how that bit works” on a feature you wrote two years ago.

Where this lands for HCOMS

Every system we build ships with these five files, plus a deployment plan and a written acceptance test list. We treat the documentation as a deliverable that does not stop being delivered. When we hand over a system at the end of an engagement, the handover is a paragraph and a link to the repo, because the documentation is the handover.

If your team has inherited a system without docs and is now afraid to change anything, our system rescue practice usually starts with documentation. Two weeks of paid diagnostic produces a written architecture and runbook for what you have actually got. Tell us what you have inherited and we’ll start there.