Why we write everything down

We are a small software studio in the most literal sense: one human, plus a cast of not-humans who — full disclosure — are AI-generated cartoon characters we use to personify the automated parts of the work. The Archivist, whose name sits on this post, is a drawing. The filing it represents is not. This post is about our documentation habits — why a small software studio like ours writes nearly everything down, and what the writing has already saved us from.

The short version: when there is one human, there is no colleague to ask “wait, why did we do it that way?” So we built the colleague out of text files.

The ledger of expensive lessons

The centre of the system is a lessons ledger: a dated list of mistakes, one bullet each. The format is strict on purpose — every entry states the general lesson and its root cause, with the date it was learned. Not a diary, not a postmortem essay. One line that a future reader, human or otherwise, can act on without any context.

The ledger has two rules. First: read it before starting work, record into it after — read first, record last. Second: prune it. When a lesson stabilises, it gets promoted into the standing documentation and deleted from the ledger. When a lesson turns out to be wrong, it gets removed rather than kept for sentiment.

A confidently-wrong ledger is worse than an empty one.

Two entries, as evidence

Documentation advice is cheap, so here are two real entries from our own ledger, lightly translated out of shorthand.

Version numbers move in lockstep, or not at all. Our WordPress plugin declares its version in three places: the plugin header, a PHP constant, and the readme’s stable tag. Once, a hand-copied zip shipped new code while all three markers still announced the old version — and a later check found a file annotated as belonging to a version the plugin didn’t yet claim to be. Nothing exploded, which is exactly what made it dangerous. The rule now: all three markers move together, every release, no exceptions.

Grep the compiled bundle, not just your source. Before sending a build off for review, we search the compiled dashboard JavaScript for external hostnames. That habit exists because it once caught a development placeholder-image service baked into the bundle, quietly requesting pictures from a third-party host on a normal admin screen. The automated checks hadn’t flagged it. For a plugin whose whole point is transparency — and which promises to make no unsolicited network calls — that would have been an uncomfortable thing to learn from someone else. We caught it ourselves, swapped the previews for inline graphics, and wrote the search into the pre-release ritual.

Documentation habits for a small software studio

The ledger is one document among several. The full inventory, at our size:

• The lessons ledger — dated mistakes, as above.
• Handoff notes — written so a completely fresh collaborator could pick up mid-project. Each one carries a section for decisions that were learned the hard way, with dates, so nobody re-litigates a rejected idea for the third time.
• Build notes — how the compiled things get compiled, so the shipped bundle is never a mystery, not even to a reviewer.
• Versioned recipes — even our image prompts live in a recipe file: the palette, the casting rules, the constraints, and an instruction not to generate the characters without following it. Once a character becomes identity-critical — the mascot, the coin — we stop re-prompting it entirely and derive new crops from the approved file instead, a decision which is, naturally, written down.

Written memory is the second employee

None of this is a productivity philosophy. It’s arithmetic. One human cannot hold a plugin, a payments setup, a review process, a public directory, and a brand’s entire visual canon in their head at once — and the not-humans, for all their charm, remember nothing between sessions. The documents are the second employee: the one who never forgets, never gets defensive when asked why something was done, and works for the cost of writing things down.

There is an honesty angle too, which is more or less our whole thing. A studio that puts labels on its own AI images should also be able to show its working. The ledger means we can say precisely what we got wrong, and when — less comfortable than a polished changelog, considerably more useful.

If you’d like to see what all this writing actually produces, the plugin lives at aimtransparency.com. The ledger itself stays in the lab. But the habit travels well, and we recommend it to anyone whose entire engineering department fits in one chair.