Here is a question worth sitting with for a moment. If the person who built your most important system walked out the door tomorrow, and you could not reach them, would anyone else be able to keep it running? For a lot of businesses we meet, the honest answer is no. The whole thing lives in one person's head, and nobody has ever written any of it down.
Documentation is the difference between a system you genuinely own and one that is quietly held hostage by whoever happened to build it.
It is the least glamorous part of any software project, which is exactly why it gets skipped. But when something goes wrong at the worst possible moment, good documentation is the thing that turns a crisis into a quick fix. Here is what it actually looks like, and why you should insist on it.
The bus factor
Developers have a slightly grim name for this risk: the bus factor. It is the number of people who would have to be hit by a bus before the project is in serious trouble. If only one person understands how your system works, your bus factor is one, and that is a fragile place to be.
It does not take an actual bus. People resign, take leave, fall ill, move overseas, or simply get too busy with other clients to answer your call. The moment that happens, a system held in a single head becomes a system nobody can touch. Documentation is how you raise that number above one.
If everything you know about your own system depends on one person picking up the phone, you do not really own that system yet.
What good documentation actually covers
Good documentation is not a fat manual nobody reads. It is a clear, practical record of the things the next person will need to know. At a minimum it covers:
- How it works. A plain overview of the main pieces and how they fit together, enough that a new developer can find their feet.
- How to run and deploy it. The steps to get it running and to push out an update safely, without guesswork.
- How to fix common problems. The handful of things that tend to go wrong, and the known way to put each of them right.
- Where everything lives. The code, the server, the domain, the database, the third-party accounts. A map of all the moving parts.
- How credentials are handled. Where the passwords and keys are kept, and how someone gets access properly, never pasted into a chat message.
Written for the next person, not the author
This is the part that separates real documentation from notes. The author already knows how the system works, so notes written for themselves tend to skip all the obvious bits, which are exactly the bits a newcomer gets stuck on.
The test that keeps it honest
Good documentation is written for a competent stranger. The right question is not "does this remind me how it works?" but "could a developer who has never seen this before get up and running from these words alone?" That shift changes everything about what gets written down, and it is the standard we hold ourselves to.
Documentation is a living thing
A document written once at launch and never touched again rots fast. Within a few months it describes a system that no longer exists, and stale documentation can be worse than none, because it sends people the wrong way with confidence. Good documentation gets updated as the system changes. It is a habit, not a one-off deliverable.
Why it sets you free
The real payoff is independence. When your system is properly documented, you are no longer locked to one developer. If you want a second opinion, a new partner, or simply someone available this week, they can read the docs, understand what they are dealing with, and get to work. You are negotiating from a position of choice rather than dependence.
That changes the whole relationship. A developer who keeps everything in their head can hold you over a barrel, whether they mean to or not. A developer who documents their work is telling you, plainly, that they expect you to be able to carry on without them. That is the kind of partner worth keeping.
Insist on it as a delivered item
So treat documentation as part of the job, not a nice extra. When you commission software, ask for the documentation to be a named deliverable, handed over with the system and kept current as things change. It costs a little time up front. It saves you enormous pain, and a great deal of money, the day you need it most.
