Finally documenting our environment properly
The senior sysadmin is the worst person to write the runbook. We've been watching how small IT teams are actually solving the "everything lives in my head" problem, and a pattern keeps showing up — one we didn't predict. The setup most people land on: voice dictation while the work is fresh. Fix something, narrate what you did for two minutes, clean it up later, drop it in the wiki. One team we've been talking to went from a 12-page wiki to 80 pages in four months this way. The surprise isn't that it works. The surprise is whose docs are better. The senior, dictating a procedure he's done a hundred times, skips the steps that have become invisible to him. The junior, narrating the same kind of work, explains it at the level someone unfamiliar would actually need — which is the level a runbook is supposed to be written at.
Finally documenting our environment properly — and the hardest part wasn't what I expected
A pattern we've been watching in the wild: small IT teams are quietly solving the documentation problem, and the trick isn't a better wiki.
documentationsysadminobservation
Every small operation has the same broken loop. The person who knows how everything works is also the person keeping it running, which means the documentation never gets written, which means that person can't take a vacation, which means there's still no time to write the documentation. We see it in two-person IT departments. We see it at the eight-table restaurant where the owner is the only one who knows the POS workaround. Same shape, different vocabulary.
The fix that's working is not a new wiki platform. It's not a Confluence-vs-BookStack debate. It's voice dictation, and the surprising part is who writes the better docs.
What the working version looks like
A solo sysadmin we've been talking to — 200-person company, recently got a junior — described his actual workflow. When he fixes something or sets something up, he narrates the process out loud while it's fresh. He uses an AI dictation tool (Willow Voice, in his case — the category matters more than the brand), talks for two or three minutes, and gets a page of rough documentation he cleans up later and drops into the wiki.
"OK so the Exchange hybrid migration required updating the autodiscover DNS record to point to the O365 endpoint, then running the hybrid configuration wizard, the TLS certificate needed to be the wildcard cert not the single domain one because…" Two minutes of that, and there's a runbook entry that didn't exist before.
Their wiki went from 12 pages to about 80 in four months. Not all polished. But it exists.
The part we didn't see coming
He had the junior start doing the same thing. The junior's docs are better.
Not because the junior knows more — he knows less. That's exactly why. When the senior dictates a runbook, he skips the steps that have become invisible to him. The junior, narrating the same kind of work, explains things at the level someone unfamiliar with the system would actually need.
Which is the level a runbook is supposed to be written at.
This is the inversion most documentation policies miss. The expert is the worst person to write the runbook for the non-expert. The not-yet-expert is the best person — for a window of about a year, before the steps become invisible to them too.
Why this works in shops smaller than a 200-person IT department
The "everything lives in my head" problem isn't a sysadmin problem. It's a small-operation problem. The owner of a five-chair salon has it. The two-truck plumbing shop has it. The dentist who's been running the same office for twelve years has it worse than anyone, because the institutional knowledge has had a decade to bury itself.
Voice dictation works for the same reason in all of them: the documentation gets written when the work is fresh, by the person doing the work, in the time slot where writing it down would otherwise be impossible. The output is rough. Rough and existing beats polished and theoretical.
If you're going to try this, two things from what we've watched:
- Have the newest person on the team do as much of the dictation as possible. Their docs will read better to the next newest person. This is counterintuitive and it's the whole game.
- Don't migrate platforms first. Whatever wiki you have is fine for now. The bottleneck is not the tool — it's the writing. Solve the writing, then decide if the tool is actually in the way.
What this isn't
This isn't an argument for a specific dictation app. The category is mature enough that several work fine. It also isn't an argument that AI generates good documentation — it doesn't. A human is still doing the thinking. The AI is doing the typing, which turns out to be the part that was eating the time.
The boring answer, again: the documentation gets written when writing it down stops being a separate task.
— Alex Kargin. More engineering writing at kargin-utkin.com.