Why We Write Documentation As We Go

Documentation written at the end is fiction

By the final week nobody remembers why the schema is shaped that way, which options were rejected, or what that workaround was for. So end-of-project documentation describes what the code does — which the code already says — and omits the reasoning, which is the only part that could not be recovered.

So we write the reasoning as it happens, in short notes, and assemble them at the end.

Code tells you what. Only a person who was there can tell you why, and they will not remember in eleven weeks.

The four documents that matter

1. README. Gets a new developer running locally in under an hour. Tested by having someone follow it exactly.
2. Deployment runbook. The precise steps, including rollback. Not a description — the commands.
3. Architecture decision notes. One short note per significant decision: what we chose, what we rejected, why.
4. Known rough edges. Compromises, workarounds and things we would do differently, written honestly.

That fourth one surprises clients and is the one their next developer values most. Every system has compromises; documenting them saves the next person weeks of archaeology.

Architecture decision notes

Half a page each, written the day the decision is made. What was decided, what alternatives were considered, why this one, and what would make us revisit it.

The value appears eighteen months later when someone asks why the system does not use a queue here. The note says: we considered it, rejected it because volumes were low and operational simplicity mattered, and would revisit above ten thousand messages a day. That is a five-minute answer instead of a two-day investigation.

What we do not write

• Comments restating what the line above does
• Generated API documentation with no examples
• A specification document maintained in parallel with the code — it always diverges
• Long onboarding manuals nobody reads past page four
• Diagrams that go stale within a month

One diagram of the overall shape is worth having. Six detailed diagrams of internal structure will be wrong by the second sprint and will actively mislead.

Comments in the code, sparingly

We comment the why, not the what. A comment explaining that a rounding rule exists because the client's accounting system rounds a particular way is valuable forever. A comment saying “increment the counter” above a line incrementing a counter is noise.

The other place comments earn their keep is anywhere the obvious implementation is wrong. Without a note, the next developer will helpfully simplify it back to the broken version.

Who it is written for

Not for us, and not for you. For the developer who inherits this in two years and has never met anyone involved — possibly one of your own hires, possibly another agency.

Writing for that person changes what gets included. It is also the most useful signal of whether a supplier expects to be replaceable, which is a thing you should want them to expect.

Frequently asked questions