Documentation is the cheapest headcount you will ever hire

The call came in at 9pm, during a movie night with his family. An executive's assistant, something urgent, a Mac that would not cooperate. He was on the phone until eleven.

He was the only person at a large organization who genuinely understood the Mac systems. Not because he had hoarded anything. Because there was never a spare two-hour block in a normal workday to teach anyone else, and the gaps in a workday are the only place training ever gets scheduled.

Two hours of his evening, free as far as the company was concerned.

There is a version of this where the company pays for those two hours once, in advance, at the going rate, and then never pays again.

I have never met an IT person who disagrees with the idea of documentation. I have met dozens who don't do it. The moral argument is settled and useless, so let's do the economic one.

A runbook works every shift and never escalates

Think about what you get for the afternoon.

A good runbook lets a help desk technician resolve a category of problem without escalating to you. It works at 2am, on the Tuesday you finally take a day off, and in the meeting you cannot leave. It costs nothing after it exists.

Documentation converts individual expertise into organizational capability, and capability is what you have been trying to buy with headcount you cannot get approved.

Let me say the uncomfortable part plainly, because there is a version of this that sounds threatening. Writing it down makes you replaceable, and that is good for you. Being the only person who can do something puts a ceiling directly over your head. The specialist whose knowledge lives in fourteen runbooks gets pulled into architecture work. The one whose knowledge lives in their head gets pulled into a 9pm phone call about a laptop, permanently, because nothing exists that would let anybody else absorb it.

I spent years on the wrong side of that. It felt like value. It was just unpaid overtime with a flattering story attached.

Monuments and tools

Most IT documentation fails for a reason that has nothing to do with laziness. It gets written as a monument.

You can spot a monument. It was authored by the most senior person available, it opens with an architecture overview, it explains why the system is designed the way it is, and it contains no numbered steps in the first two screens. Somebody put real effort into it. Nobody has opened it since the week it shipped.

A tool looks different. It has a trigger at the top telling you when to use it. It has exact button names, because "navigate to the security settings" is a hint dressed up as a step. It ends with a way to check whether the thing worked.

Here is the test I use now, and it is the only one I trust: can the least experienced person on your team complete the task without asking you? If they come and ask, the document failed. Not the person. Take the question they asked and put the answer in the doc, because the question is free QA data and you only get it once.

One K-12 team has this right in a way I find slightly funny. Their internal documentation was AI-generated, which made it thorough and extremely long, and their next project is having their own student help desk workers rewrite it in plainer language. Their phrase for what it needs: "more human language." The least experienced people on the team get the editing pen, which brings me to the best documentation insight I know.

Your newest hire writes better onboarding docs than you do

The person who just went through your onboarding process has better information about what is confusing than the person who built it. The builder is too close. You cannot see the step you skip automatically, and you have been skipping it for four years.

So stop assigning the getting-started guide to your most tenured engineer. Assign it to the person who joined six weeks ago, and let your tenured engineer review it for accuracy rather than write it from scratch.

The other reframe that gets people over the hump: write it for future-you first, and for other people second. Future-you has forgotten the flag order. Future-you is doing this at 4:40pm on a Friday in eleven months, mildly panicked, and will be extremely grateful that past-you spent six minutes on a numbered list. If the note happens to live somewhere shared, everybody else benefits as a side effect, which is a much easier sell than altruism.

Explaining a process is also how you discover the parts you do not actually understand. Junior admins who write KB articles get better faster, and I have never seen an exception.

"Don't touch this part" is documentation that transmits fear

I once inherited an environment with about sixty scripts in it. No categories, no notes, no author on anything. One was named "test. Do not use." and it was live in three policies.

Inside another one, in a script that ran at every enrollment, there was a comment: "don't touch this part."

That comment is documentation, technically. It transmitted exactly one thing to me, which was anxiety. It did not transmit why, or what breaks, or which downstream system depends on the ordering of those four lines, so it made me slower without making me safer.

Compare the version that takes twenty extra seconds to write: "this sleep is here because the directory service takes about 8 seconds to respond after a network change, and without it the next command fails silently on wireless." Now I can maintain it. I can decide the risk is acceptable.

Fear-based documentation is the most common kind in IT. It accumulates in comments, in wiki pages that say "ask Dave before changing," and in the shared understanding that nobody restarts that one service on a Friday. It preserves the precise amount of knowledge required to keep everyone dependent on the original author.

What it costs when the knowledge has one address

A new hire's phone arrived with no apps on it. The help desk burned hours and never found the cause, because the script that checked for that exact expired token lived on one consultant's laptop, and the consultant was on vacation.

The script existed. The knowledge existed. Neither had an address the organization could reach.

That story is small. Here is the same failure at scale. A merged city-county government inherited a fleet of roughly 3,500 mobile devices from a single administrator who refused to document anything, and who turned out to be doing other things wrong as well. The result was an 18-month internal audit running in parallel with a platform migration. Eighteen months of staff time, spent reconstructing decisions that were never written down.

Their fix was structural rather than heroic. They distributed view and manage access out to departmental tech liaisons, one of whom now handles more than 200 devices directly, and they trained the whole asset-management team so that no single person is the dependency anymore.

The line from that team I keep coming back to is not about audit risk at all. The lack of documentation, they said, "also prevented our users from getting a really good experience."

Read that again if you have been arguing for documentation on engineering grounds and losing. Undocumented environments produce bad customer service, mechanically: requests wait for one person, answers vary depending on who picks up, and a department that could self-serve in ten minutes waits four days for a specialist who is buried. Documentation is a customer-service control, and it is far easier to fund on those terms.

The version that unsettles me most involves a maintainer who has run a widely used project for over fifteen years, is candid that he will not be doing it for another fifteen, and has spent years trying without success to hand it off. He is not hiding anything. Succession still is not happening, because handing off knowledge requires it to exist in a form another person can pick up cold, and that work never feels urgent until the week it becomes impossible.

Shouting it from the mountaintop

There is a second cost, and it lands on you rather than on your users. Infrastructure work is invisible by default. Nobody notices the enrollment failure that stopped happening, so broadcasting completed work where leadership and the help desk can see it counts as a survival skill rather than bragging.

A COO once messaged a team over lunch to ask when a particular feature could be built. It had shipped in February.

Unannounced work gets requested again, and sometimes rebuilt from scratch by somebody else. Expensive, for a problem that three sentences in a channel would have solved.

Assume nobody follows it as written

This is where I was wrong for the longest.

I believed that if the document was accurate, the outcome was determined. Consultants who run platform migrations for a living put it better than I can: if you produce documentation and you assume everyone else is going to do exactly the same thing that you do, you are already in trouble. People interpret instructions in ways you would never predict, and adding a screen recording does not close the gap.

Their recommendation is to watch pilot users attempt the procedure live, before it goes anywhere near the rest of the company. Not a survey afterward. Watch, in real time, and stay silent while they get stuck.

I resisted this for years because it felt condescending, and it is the reverse of condescending. It is the only test that evaluates the document instead of the person. Every place they hesitate is a defect, and you will find four of them in ten minutes.

What to write first

Nobody has time to document everything, and any plan that requires it fails in week two. Go in this order.

1. The thing you were paged for most recently. Write it while the annoyance is fresh. This is the highest-value document you will ever produce and it takes fifteen minutes.
2. Your top five ticket categories. Password and access requests, enrollment failures, VPN, printing, whatever your actual top five are. These are the ones that let tier one stop escalating.
3. Anything only you can do, ranked by what it costs if you are unreachable for a week. The scary ones go first.
4. Every credential, token, certificate, and contract with an expiry date. Where it lives, who owns it, when it renews, what breaks when it lapses. The location of the secret, never the secret.
5. Onboarding, drafted or rewritten by your newest hire. Yes, really. They are better at it than you.

And a minimum standard, so nobody has to guess what "documented" means:

• A trigger line at the top: who this is for, and when to use it.
• Prerequisites: access, permissions, tools, and where the credentials live.
• Numbered steps with exact commands and exact button labels.
• A verification step, so the reader knows they actually finished.
• A failure path: what it looks like when it goes wrong, and who to escalate to by role, never by name.
• A last-verified date and the name of whoever verified it.
• One screen if you can manage it. If it needs three, it is probably three runbooks.

The last-verified date matters more than it looks. Docs age even when they exist, and a page describing a console layout from two OS releases ago is worse than no page, because it burns the reader's trust in every other page you wrote.

The part that is actually about your career

I know why this work never gets done. It has no deadline, no requester, and no ticket number, so it loses every single time it competes with something that has all three.

The reframe that finally worked on me had nothing to do with best practices. Every hour of knowledge you keep in your head is an hour somebody will eventually extract from your evening, your vacation, or your last two weeks at a job you are trying to leave gracefully. That is the interest rate on undocumented work, and it compounds the longer you stay.

The people I know who get promoted fastest are the ones whose teams run fine without them for two weeks.

Write the runbook. Then go watch the movie.

---

Foqal brings IT support into Slack and Microsoft Teams, where the answer somebody already wrote down can actually reach the person asking.