The Documentation You Wish You’d Written 18 Months Ago
Five documents that save real pain — and the four that don’t
By Steele Consulting
Every operator who has lived through a critical employee’s departure knows this specific feeling. The person is leaving. You’re sitting in a conference room trying to download everything they know. Three days of knowledge-transfer meetings. A hastily-written wiki page. A promise to answer questions by Slack after their last day. And the quiet knowledge that it won’t be enough.
Six weeks later, something breaks that only they knew how to fix. You spend a day figuring out what you should have been told. The whole team pays for a gap that didn’t need to exist.
This is the documentation gap. And unlike most problems we write about, this one has a specific temporal shape: the right time to fix it was 18 months ago. The second-best time is this quarter — before the next person leaves, before the next incident, before the next DD, before the next transition.
In our 24 years at Steele Consulting building and inheriting other people’s custom software, we’ve seen the same pattern repeat: teams document a lot of things, and most of what they document doesn’t help them when it matters. The gap isn’t between businesses that document and businesses that don’t. It’s between businesses that document the specific things that save pain, and businesses that document the generic things that feel productive.
This post is about the five documents that actually matter — and the four that don’t, so you can stop wasting cycles on them.
Why most documentation fails
Three reasons repeat across almost every documentation effort that ends in a wiki nobody reads.
Written at the wrong time
Documentation written in a year-end push is stale by Q2. Documentation written during the actual work — right after the incident, during the vendor evaluation, when the new system goes live — stays accurate because it’s grounded in the context that produced it.
Written for the wrong audience
Most docs are written for “someone” — a hypothetical reader who doesn’t exist. Good docs are written for a specific person: the engineer who will inherit this on Monday, the on-call responder at 2am, the new hire in their first week. That specificity shapes what gets included and what gets left out.
Written by the wrong person
The expert who knows the system knows too much. They forget the context the reader needs. The best docs are often written by someone one step less experienced — the person who had to figure it out recently and still remembers what was confusing.
With that in mind, here are the five docs that are worth your team’s time.
The 5 docs you’ll wish you had
1. The Weird Stuff Doc (per critical system)
For each system the business depends on, one document that captures the things that aren’t obvious: the undocumented business rules buried in the code, the manual process somebody runs every quarter, the specific edge case that trips up new engineers, the configuration that looks wrong but is correct for a specific reason.
This is the most under-written document in software. It’s also the single highest-return document when someone new has to operate the system. If a document could save a new engineer a week, it’s this one.
Write it by having the person who currently operates the system walk a less experienced engineer through “the stuff you wouldn’t guess.” Capture that conversation. That’s your document.
2. The Decision Log
One running document per team or product. Every meaningful technical decision gets a two-paragraph entry: what we decided, what we considered, what we chose instead, and why.
The entries that matter most are the ones about what you didn’t do. “Why don’t we use X?” is a question new team members ask constantly, and without a decision log, somebody has to re-reason the answer every time. Worse, without it, teams reopen decisions that were already made for good reasons that nobody remembers.
The decision log is what prevents your team from quietly re-making the same bad decisions as it grows.
3. The Incident Playbook
For each system where real downtime matters, a playbook for the specific incidents that have happened before. Not generic incident response — the actual steps for the actual incidents your team has seen.
“When this specific thing starts behaving this specific way, here’s what to check, in this order.” The playbook is a direct output of a good post-incident review. If you aren’t writing an incident playbook update after every meaningful incident, you’re guaranteeing that the next version of the same incident takes just as long to resolve.
4. The Vendor & System Registry
One living inventory of every system, service, and vendor the business depends on. For each entry: what it does, who owns it internally, who to call externally, how much it costs, when the renewal is, whether the contract has change-of-control implications, and what happens if it fails.
We wrote about the broader version of this in Your Company Is Paying for 47 Software Tools — the audit view. The registry is the ongoing document that makes the audit discipline permanent.
This document is also the single most-asked-for artifact in tech due diligence. If you ever plan to raise capital or sell the business, you’ll be writing a version of this at the worst possible time. Writing it now, maintained quarterly, means it’s ready when you need it.
5. The “Who to Call” Doc
A document that answers specific operational questions: who owns which part of which system, who has access to what, who to escalate to in each specific scenario, who holds the credential for the thing that only one person knows.
The classic version is a spreadsheet. The better version is a one-page doc with scenarios (“the payment processor is throwing errors — who handles that?”) rather than roles. The scenario format works because it’s how questions actually arrive in a crisis — not “find me the owner of X,” but “something is broken, who do I call?”
What’s typically written but not worth your time
Four things get documented regularly and reliably fail to earn their keep:
- API documentation auto-generated from code. Machines read it. Humans don’t. If an engineer needs to understand what an API actually does in context, auto-generated docs won’t give them that. Save the effort.
- Setup and onboarding instructions written more than three months ago. They’re stale. Everyone knows they’re stale. Nobody reads them past step 3. Replace with a short, dated “last known good” doc that explicitly says what to verify and what to update.
- Overview wikis for the whole business. Written for an imagined comprehensive reader who doesn’t exist. Nobody opens them when something is actually broken. The specific docs above beat one giant wiki every time.
- Meeting notes used as reference docs. Meeting notes are notes from a meeting. They aren’t a reference. If a decision came out of a meeting, it goes in the decision log — not in the notes.
The maintenance question
A document that isn’t maintained is a liability, not an asset. The team starts trusting it until it goes stale. Then they stop trusting any documentation.
Three disciplines keep docs alive:
- Named owner per document. Not “the team owns it” — one specific name. If nobody owns it, it will die.
- Quarterly review calendar. Each doc gets reviewed on a defined schedule. 15 minutes per quarter per doc. Add it to the calendar.
- “Updated when things change” culture. When the system changes, the doc changes in the same PR, pull request, or ticket. Not as a follow-up. In the same unit of work. Teams that bolt documentation on later never catch up.
How this connects to the other decisions you’re making
The documentation gap sits downstream of several other patterns we’ve written about. The Key-Person Cost from The Real Cost of an Underbuilt Tech Team is what documentation closes. When a Spreadsheet Becomes a System often starts with an undocumented spreadsheet that quietly became load-bearing. The Secondary Owner Program we described in How to Prepare Your Tech Stack for an Exit depends on real documentation existing — without it, there’s nothing for the secondary owner to learn from.
The through-line is simple: the documentation you’ll wish you had is the specific documentation that would have reduced your Key-Person Cost, your DD risk, your incident response time, or your onboarding ramp. Those four are the real returns on documentation effort. Everything else is just reading practice.
Book a call
Twenty-four years of building custom software. Both sides of the table on more decisions than we can count. And a track record of telling clients honestly when the answer is us and when it isn’t.
If you’re sitting in the middle of this decision right now, that’s the conversation we’re built for. Book a 30-minute call and we’ll walk through it with your specific situation. No pitch. No pressure. You’ll leave with a clearer picture of what to do — whether you work with us or not.