I have inherited some truly terrible process documentation. There was one SOP that started with “Sync the data” as step one. That was the entire explanation. Sync with what? How? What does “sync” even mean in this context? The person who wrote it knew exactly what they meant because they’d been doing it for three years. To everyone else, it was a wall of assumed knowledge.
Most process documentation is written by the person who already knows the process, for themselves, not for the person who doesn’t. The result is SOPs that skip all the obvious bits because they’re so obvious to the author that they can’t imagine anyone not knowing them. Steps that assume context you don’t have. Screenshots that don’t match your screen because something changed and the documentation wasn’t updated. Decisions presented as facts without explanation. And the phrase “as usual” used in a way that suggests there’s a usual that everyone knows but that’s actually completely undocumented.
The problem is that writing good documentation requires you to reverse-engineer your own knowledge. You have to do the task while pretending you don’t know how to do the task. You have to anticipate the places where someone will get stuck. You have to explain the “why” not just the “what.” This is hard. It’s much easier to just write down the steps the way you know them.
But it’s also the thing that separates operational documentation that actually gets used from documentation that sits on the wiki never-consulted, creating the false impression that processes are documented when they’re really just written down in a way nobody can parse.
The first practical rule is to document while you’re doing the task, not from memory. Not later that afternoon. Not the next day. Not next week. Physically go through the process and write down every step as you do it. This seems tedious. It is. But it catches all the tiny stuff you’ve automated in your head.
You sit down to back up the database. You don’t think, “I need to turn on two-factor authentication for production access.” You just do it because you’ve done it five hundred times and your hands know the sequence. But someone else doesn’t have five hundred instances of muscle memory. They need to know that step. Writing it down while you’re doing it means you don’t skip the automatic bits.
This also means screenshots. Real screenshots of what you’re actually looking at. Not a generic image from a tutorial. Your actual interface with your actual data. This sounds trivial and it’s not. If the documentation says “click the button in the top right” and the button is in the top left on the screen the person is looking at, they’re stuck. They think they’re in the wrong place. They start doubting the documentation. They ask someone else instead of just doing the task.
The second rule is to include the “why” not just the “what.” Not in an abstract way. In a practical way.
Step 5 is “Check the database consistency report.” The “what” is what the step is. The “why” is that you need to know if there’s data corruption before you run the sync, because if there is, the sync will propagate it. That’s a very different kind of information from just “check the report.” It tells the person why the step matters. If something is skipped or the report looks clean, they understand why that’s okay.
This doesn’t mean writing a novel. It means a sentence or two that gives context. “The report will show X if there’s a problem. If you see X, stop and contact the database team before continuing.” Now the person knows what they’re looking for and what to do if they find it. They can make a decision instead of just following instructions.
The “why” also helps when something changes. If the system gets updated and that step changes, someone who understands why the step exists in the first place can adapt the documentation accordingly. If they just know the steps, they’ll write down the new steps with the same lack of context, and the documentation becomes increasingly useless.
The third rule is to anticipate where people get stuck and explain that bit in painful detail. There’s usually one point in any process where people always slow down. They’re confused. They’re not sure if they’re doing it right. They’re about to give up and ask someone else.
In the onboarding process I used to run, that point was always the moment people had to set up API credentials. They knew they needed credentials. They couldn’t quite figure out where to find them or how to format them. The documentation said “set up API credentials” and moved on. People would be stuck for an hour, then ask someone else who would spend five minutes explaining it.
I rewrote it to walk through exactly where to find the credentials page, what the page would look like, which field was which, what format they needed to be in, and what error message they’d see if they got it wrong. Half the documentation is about this one step. That’s not excessive. That’s meeting people where they get stuck.
You can usually figure out where this point is by remembering your own learning curve. The moment when you didn’t know what you were supposed to do. The question you had to ask. The assumption you made incorrectly. Write the documentation for that moment.
The fourth rule — and this one is crucial — is to test it on someone who doesn’t know the process. Not someone who almost knows it. Not someone who does something tangentially related. Someone who has never done this thing before.
Ask them to follow your documentation step by step. Watch them. Don’t help them. Just watch. If they get stuck, you’ve found something that needs to be clearer. If they do something you didn’t expect, your documentation wasn’t specific enough. If they ask a question, your documentation needs to answer it.
This is uncomfortable. You’ll watch someone struggle with something you think is obvious and you’ll have to resist explaining it. Do it anyway. That discomfort is the documentation telling you it needs work.
You’ll be surprised by what trips people up. The thing you thought was perfectly clear will confuse them. The thing you glossed over will stop them dead. This is valuable information. Take it and rewrite.
Once you’ve done this — documented while doing, added the why, explained the hard parts, tested on someone new — you’ve got documentation that actually works. Someone can pick it up, follow it, and complete the task without coming to find you.
This is the operational grease that scales. When you can hand someone a task and a piece of documentation and they can actually do it without constantly asking for clarification, you’ve freed up enormous operational capacity. You’ve also freed yourself up. That time you were spending explaining the process over and over — that time becomes available for something else.
The hardest part is the mental shift. You have to stop thinking of documentation as something you write to satisfy a compliance requirement or to check a box on a “we need to document things” initiative. You have to think of it as a tool that does real work. It’s literally replacing you having to explain the process. If it doesn’t work as well as you explaining it, it’s not good enough.
That’s a high bar. It’s worth meeting.