Improve Article Show
Save Article Like Article Improve Article Save Article 1. Program : 2. Instruction : Difference between Program and Instruction :
Laura is a technical writer. She enjoys playing the piano, traveling, fine art, and making jewelry. Writing computer instructions Copyright © 2012 Laura D. Schneider. All rights reserved. Put Yourself in the Reader's ShoesTo 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 ReadersFirst 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:
A frustrated user about to turn to the documentation for help. Copyright © 2013 Laura D. Schneider. All rights reserved. Your Readers Are Already FrustratedAs 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 InstructionsBefore 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
The Magic Formula: The Given-New MethodNow 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 InstructionsNow 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. For example:
Final Clean-UpWhen 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 InstructionsOnce 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 GeneralizationsWe can make the following conclusions and generalizations about writing software instructions:
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: Earl-- 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. Cheers! --Laura 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. |