Documentation Nobody Wrote

Three years after go-live, somebody needs to change a rule. Nobody knows what the automation does, the person who built it has left, and the safest available option is to leave it alone.

At that point the automation is no longer an asset — it is a constraint. Four documents prevent this, each takes under an hour, and they are the first thing cut when a project runs late. A product-side example of how workforce software approaches this topic is available in this page.

The four

One. What it does, in prose. A page. In each case, this happens. Written so an operations person can read it without opening the implementation. If the only description of the logic is the code, nobody can verify the automation is doing what was intended, and nobody can change it safely. For broader background and an independent point of comparison, see OpenAI Business.

Two. What it does not do. The exception list with reasons — which cases route out and why. This is the boundary, and it is more useful in year three than the description of the happy path.

Three. What it depends on. Which systems, screens, fields, formats, credentials. This is the document you read when something breaks, and it converts a day of investigation into ten minutes.

Four. How to change it. Who edits what, how it is tested, how it is deployed, who approves. Without this, every rule change becomes a procurement exercise.

Why they do not get written

They are the last item and the project is late. Documentation is scheduled at the end, and the end is where the compression happens.

They have no audience at the time. Everyone involved knows how it works, so writing it down feels redundant. The audience arrives in eighteen months, when the writers have gone.

And they are not billable to anyone. The vendor is not paying for future maintainability and the internal sponsor is measured on delivery. Nobody's incentive points at it.

Making them exist

Require them as a payment milestone, not a deliverable at the end. A retained percentage against a listed documentation set changes what happens.

Write the first one before the build. The prose description of what it should do is a specification. Writing it first gets it written, and it also catches design disagreements while they are cheap.

Keep them where the automation is, not in a project folder that gets archived when the project closes. This sounds trivial and it is one of the commonest reasons documentation that exists is never found.

And update them when the rule changes — which happens only if the change procedure says so, which is document four.

The test

Hand the four documents to someone who was not involved and ask them to make a small change.

They will find the gaps in an afternoon, while the people who could fill them are still available. Doing this after handover, with the original team gone, is how organisations discover that the documentation describes a version from eighteen months ago.

What to write when it is already too late

An inherited automation with no documentation. Do not attempt a full reconstruction.

Start with what it depends on. Watch it run, log what it touches. This is the highest-value document and the easiest to produce from observation.

Then the exception list, from the routing logic or from the queue.

Then the prose description, which is the hardest and can be built up over a few months as things come up.

And write the change procedure first regardless, because it costs nothing and it prevents the next undocumented change.

The short version

• Four documents: what it does in prose, what it does not do, what it depends on, and how to change it
• Each takes under an hour and all four are cut when the project runs late
• They have no audience at the time and the audience arrives eighteen months later, after the writers have gone
• Require them as a payment milestone, write the prose description before the build as a specification, and keep them with the automation
• Test by handing them to someone uninvolved and asking for a small change, while the original team is still available
• For an inherited automation, start with the dependency list — it is the highest value and can be built from observation