Laura is a technical writer. She enjoys playing the piano, traveling, fine art, and making jewelry.
Put Yourself in the Reader's Shoes
To write better computer "how-to" instructions or procedures, you must first put yourself in the reader or user's shoes.
The user knows nothing about your website or piece of software and won't (and shouldn't need to) take the time to read the entire set of instructions before beginning their work. The user is simply using your product to accomplish some goal of theirs (make a purchase, look up information, and so on).
What You Need to Understand About Your Readers
First things first. You need to accept the fact that your readers very likely do not want to be reading what you wrote. This means that in order to write effective, helpful instructions, you first need to accept all of the following truths:
- Your readers/users don't want to learn how to use your product/service; they want to accomplish some task or goal of their own.
- They only read the documentation in desperation after what they tried to do failed.
- They are now frustrated.
- They are lost as to how to proceed to complete their goal/task.
Your Readers Are Already Frustrated
As a writer of instructions, you're starting in a bad situation because users (whom you probably don't know and will never meet) are already frustrated with your product/service by the time they turn to the instructions you've written on how to accomplish each task. So, be kind to them and give them clear, concise, definitive, accurate instructions that put them back on the path to achieving their goal as quickly as possible: It's a form of good customer service!
The pattern becomes quite easy and is applicable to most types of step-by-step instructions, not just computer instructions.
A Note Before You Begin to Write Instructions
Before you begin to write instructions, you need to know what style they should be written in.
Ask around for a "House Style Guide" (the marketing department is a good place to start) and get the latest copy of the Microsoft Manual of Style for Technical Publications. But what about Apple Macintosh users? They're either already familiar with the Microsoft style of writing or they won't be confused by it because you'll be implementing the style of writing consistently throughout the instruction manual.
A dictionary and thesaurus never hurt, either, though these can be found on the Internet, also, and which one(s) to use should be specified in the House Style Guide. If in doubt, use Merriam Webster, the "gold standard" of dictionaries.
The Magic Formula to Writing Instructions
|Where Am I?||What Should I Do?||What Happened?|
Tell the reader where they are →
Tell them what to do →
Describe the results of their actions
The Magic Formula: The Given-New Method
Now you know one of the basics of technical communication, whether or not you're a professional writer. It's also known as the given-new method because you start by telling the reader something they already know, a "given", and then you give them something "new". Clear titles/headings are the keys to success here.
Note that this method helps the already frustrated reader/user quickly understand whether your particular procedure applies to their situation because you gave it a clear title, whether they are in the right starting place (because you told them where to start from), what to do at that point, and what the results should look like.
Now You're Ready to Write Good Instructions
Now that you know the rules for writing, you can begin to write the instructions keeping the user's perspective in mind at all times.
You title the instructions "How to do task ABC", making sure that the instructions under this heading all have to do with accomplishing task ABC (and nothing else). Now you're ready to write the instructions themselves.
The first thing to do is to orient the users: tell the users where they are and what they should be seeing on their screen, such as the name of the window they should be looking at. Next, tell them what button(s) to push on the current window and/or what text they need to type into what field(s). Next, tell them how to get to the next step/location and describe what they should see onscreen when they take that action.
- From the Main Window, select all of the options that you want to activate. Click OK. The Second Window appears, showing the current status of the options you selected.
- On the Second Window, verify that all of the options selected are correct.
- If all options are correct, click Activate Options. The Third Window appears.
- If the options are not all correct, click Back to return to the Main Window and select different options.
When you're done writing, run the spelling and grammar checker, then have one or more subject-matter experts (SMEs)—people who know the product—review the document. Make any changes, re-run the spelling and grammar checker, and have someone proofread/edit the document.
Once you've entered any changes the editor has made, you're generally finished (unless your company has a formal document release process, which you should follow).
Note that the changes made by the subject-matter experts and the editor (the subject-matter export on the exact wording and style) should be accepted almost without question: it is their job to know their area of expertise. If you strongly disagree with a change, only then bring it to the attention of the SME or editor as the case may be. Otherwise, make the suggested changes.
Usability Test Your Instructions
Once you have a very good draft, recruit several people to test your instructions—to go through them from start to finish and note (and allow you to note) any areas in which they get lost or confused or where the instructions are wrong.
Ideally, usability testers should be the real customers/users of the product/website you documented. However, in a pinch recruiting a few people from around the office who are unfamiliar with what you have written about and having them test the document is better than nothing. In this case, note that the testers are the subject-matter expert users, so their changes are just as valuable as those of your product SMEs and editor (SME).
Usability testing itself is a whole discipline that is too broad to cover in this article.
However, once you have made usability testing changes, run the changes past the editor and, if applicable, your product/service SMEs: perhaps a small change in the product/service, either now or in a future release, would make a huge difference to the users.
Conclusions and Generalizations
We can make the following conclusions and generalizations about writing software instructions:
- Readers are frustrated when they are reading your work.
- You need to put the reader at ease by telling them where they are, what to do, and where they will end up.
- You need to have experts review your document for product accuracy as well as writing accuracy.
- You need to accept the changes made by your experts unless you significantly disagree, in which case talk to the expert in question about the issue.
- Usability testing is the best way of making sure that your document will be a success at meeting the users'/readers' needs. It may even lead to product improvements!
This article is accurate and true to the best of the author’s knowledge. Content is for informational or entertainment purposes only and does not substitute for personal counsel or professional advice in business, financial, legal, or technical matters.
© 2009 Laura Schneider
Laura Schneider (author) from Minnesota, USA on July 13, 2012:
Alison, I'm not seeing an accuracy problem with that sentence. Would you please explain what you're seeing that I'm not?
alison on July 12, 2012:
...click Activate Options and the Third Window appears, otherwise click Back...
Check above sentence for accuracy.
Laura Schneider (author) from Minnesota, USA on November 28, 2009:
Excellent point! I agree whole-heartedly.
Having users from your target audience (intended users) and random clueless people "off the street" (someone from another department, a student intern, etc.) all test the instructions and give their feedback is the best way to go.
And, of course, if you have a professional editor on staff, don't forget to have the editor review your instructions.
Earl Hemminger on November 27, 2009:
You left out the need to have several users test your steps. No matter how idiot proof you make your directions someone is a better idiot and will find a way to break your directions.