How to Write a How to Guide

This is TokenUser’s submission for the HP Magic Giveaway. Feel free to leave comments for this article as you see fit – your feedback is certainly welcomed! If you’d like to submit your own how-to, what-is, or top-five list, you can send it to me. Views and opinions of this writer are not necessarily my own:

Before writing a guide on how to do something, there are a couple of questions that you need to ask yourself … do you know the subject well enough to explain it in simple terms? And, can you write a concise set of instructions based on that explanation?

If you are good to go on these questions, the best How-To guides follow an age-old and simple principle: KISS. Keep It Simple Stupid, or (in this case) Keep It Stupidly Simple. This will enable someone to more easily follow your instructions. I’m hoping to help you write better how-to guides with this guide of my own.

Stuff You Need:

• Original idea (or a better explanation of someone else’s idea)
• Know your target audience
• All equipment on hand for a practical demonstration
• Time
• Patience
• Spell Checker
• Someone to proofread

Step 1: Tell people what you are going to tell them.

The internet is a cruel place. If someone cannot find what they are looking for above the fold (i.e., on the first page of a normally-formatted Web page), they are going to hit the back button and try the next item in their Google results. You need to tell people what you will be telling them about. In traditional terms, this is an abstract – but the internet is far less formal (!) than that. An introductory section or paragraph will work just as well.

Step 2: Tell people what they need to perform the how-to you are documenting

This is like the ingredients list in a recipe. You need to be up front about any tools or ingredients someone will need. Pointless getting to the 10th step of a 12-step process to find that you need a 12.5mm socket wrench. If it’s going to be needed, tell ‘em up front.

Step 3: Break it down

Take the process and break it down to its simplest components. Don’t go overboard, but do break it down (e.g., using the Phillips head screwdriver or small socket, remove the screw hold the side panel, and then pull the panel towards you then up to remove).

Step 4: Educate

The best how-to guides will have you learning something new. So, take the opportunity to educate as well. Chances are, the person reading the guide is new to the subject (otherwise, why are they are a how-to on it), and some education might be better than just spoon-feeding the steps. There are two ways to do this: a breakout box with an explanation, or explaining inline with the instructions.

For example:

1. In the Mac OS X Terminal, type “cd Desktop” (same as in Windows, cd changes directory).
2. Now, confirm that the file is in that directory by typing “ls” (this command is like the “dir” command in Windows, and will list all the files in the directory). You should see the text file you downloaded. There are lots of options available for the ls command – type “man ls” to see them all. If the file is not shown in the list, make sure you are in the Desktop directory (it will be listed in your command prompt, or type “pwd” to see where you currently sit). You may have to download the file again, making sure it is on your Desktop.
3. Now type “cat filelist.txt” (cat is a “type” command, it displays the contents of the file on screen).
4. Next, type “cat filelist.txt | xargs ftp” – you are building a command chain here, with the “|” (pipe character) indicating that you want the output from the left side used as the input for what lies on the right side. xargs builds an “argument list” based on the contents of the text file you piped in via the cat operation, then feeds it to the ftp program.
5. You should then see the files starting to download, one by one.

Step 5: Anticipate

The best how-to guides anticipate problems someone might have, and ensure that the environment for executing the steps is consistent. Steps 1 and 2 in the above example are setting up the environment consistently (i.e., making sure people are in the same directory for starting the procedure), and telling people what to do if the step fails. Examples are important, as they give the reader a comfort level with what they are expecting to see. If this is a practical guide, photos or screen shots are ideal (as they show where someone should be for each step).

Step 6: Conclusion

Tell people what they just did, and confirm that the end result is as expected. This is often in the form of a summary that bulletpoints the highlights of the how-to – a post implementation checklist.

Summary

• How-to guides need to be clearly written, and contain examples. If it is a practical guide, images are ideal.
• Sentences should be short, unambiguous.
• Style needs to remain simple – less distraction from the subject at hand.
• Content needs to be tested. Once you have written the how-to, go and perform the steps outlined. Have someone else do it as well. Can something be explained more clearly in one section? Have you assumed something that not everyone will know?
• Spell check is your friend, but it doesn’t protect you from using the wrong word or the proper word incorrectly. This is the internet, but there are no excuses for being sloppy. Your work will have greater credibility if it easy to read.
• A how-to is not a PhD thesis – remember Keep is Stupidly Simple.