If I had a dime for every time I have followed a long set of instructions incorrectly, encountered an inscrutable error, and had no idea what step I missed or where I went wrong, I’d have gotten another dime today.

In the software world, processes are often discovered backwards. We start with the final step, try it out, and see that it doesn’t work. After some head-scratching, we figure out what’s wrong, come up with a fix, then try the final step again. Something else is broken. Find a fix. Repeat. Until we have a sequence of steps that all work when done together in order.

So I tried to frobnicate, then discovered I need to grizzle, wobble, and memnify before that would work. I write my instructions to others following in my path:

1. Grizzle the gear. Make sure to do this.
2. Don’t forget to wobble the wingnut.
   • Unless you’re on a Wombo system, then don’t do this.
3. Failing to memnify the mongus will cause errors later.
4. Frobnicate should now work.

Or the even more pernicious

1. Grizzle the gear. Make sure to do this.
2. Failing to memnify the mongus will cause errors.
3. Frobnicate should now work.
   
   Note: Don’t forget to wobble the wingnut after grizzling.
   Note: On Wombo systems, don’t memnify.

If frobnicate does not work at the end of my following your steps, then not only am I forced to guess what went wrong or, at worst, start over, but if someone else experiences a problem that you already solved, they cannot search the wiki or slack or whatever where this is hosted and avail themselves of your debugging prowess. And in the second example, there’s a good chance I did the three steps before I even read the note about grizzling, so these instructions wasted my time and I have to start over.

You know the trope where the mad scientist is talking to his guinea pigs over the radio and we hear him say, “Now, most importantly, and listen carefully here: whatever you do, under no circumstances should you ever—” and the radio cuts off?

Yeah, technical docs shouldn’t read like that.

If you want to maximize the utility of your instructional documentation, keep these requirements in mind:

1. Establish a linear structure for the reader. List exactly the steps that are necessary and sufficient to accomplish the goal, in order.
   • Avoid the temptation to streamline your instructions by describing “good path” things first and errors later.
   • If you must break this rule, try to leave links inline.
2. At each step, try to describe what the person will see if they do that step wrong, and when it will go wrong, including error messages.
3. Assume people are not going to read through your instructions in their entirety before starting on them.
   • This means put any conditionals before the instructions that they apply to.
4. Try to break the curse of knowledge by anticipating what will confuse someone, and document it inline with that step.
   • A common example is output from a step that makes it look like the step failed when it really didn’t.
5. Add “landmarks” to help people know whether they’re on the right track without having to wait until the very end.
   • This could be something like “The third LED light should be green,” or “this will produce a file named log.txt in the working directory.”
6. Document external factors that could invalidate or modify the instructions when you can.

If I had to summarize these steps and the intent behind them, I’d probably say it like this:

The best technical documentation places relevant information closest to where it will be needed.

Compare these instructions with the above examples:

1. Grizzle the gear. This is required to wobble later.
   • If you don’t, you’ll get the error “Unable to wobble: error 42” in step 2.
2. Wobble the wingnut.
   • You can safely ignore the “PANIC: flexor not responding” messages in the output.
   • If you miss this step, frobnicate will hang and eventually segfault.
   • You should see output on the serial console after this step. If you don’t, file a bug report.
3. If you’re not running Wombo, memnify the mongus.
   • This fixes “Error: France” in frobnicate.
   • We can remove this step after closing issue #13943, but not removing it shouldn’t hurt anything.
4. Frobnicate should now work.

Much better. Pertinent information is much closer to where it might be needed; anyone who ever experiences “Error: France” can do a wide-net search and find your fix; and the instructions can be simplified later on.