How to Write Effective Computer Instructions

Updated on September 23, 2016
Source

When Writing Instructions, Put Yourself in the Reader/User's Shoes

To write better computer "how to" instructions or procedures, you must first put yourself in the 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.).

Accept the Facts: Your Readers Don't Want to be Reading What You Wrote

So, to write effective, helpful instructions you first need to accept the generalized facts that:

  • 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 AND
  • the only read the documentation in desperation, after what they tried to do failed AND
  • they are now frustrated, AND
  • they are lost as to how to proceed to complete their goal/task.

Frustrated User

A frustrated user about to turn to the documentation for help.
A frustrated user about to turn to the documentation for help. | Source

Your Readers/Users 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

About 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 key 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 are 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.

For example:

  1. 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.

  2. 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

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 significantly 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.

What is Your Experience?

Have you ever written instructions, especially computer instructions?

See results

Given-New Method of Writing Instructions

If you have written instructions, have you used the "given-new" model to orient your readers?

See results

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!

Questions & Answers

    Comments

      0 of 8192 characters used
      Post Comment

      • Laura Schneider profile imageAUTHOR

        Laura Schneider 

        6 years ago from Minneapolis-St. Paul, Minnesota, USA

        Alison, I'm not seeing an accuracy problem with that sentence. Would you please explain what you're seeing that I'm not?

      • profile image

        alison 

        6 years ago

        ...click Activate Options and the Third Window appears, otherwise click Back...

        Check above sentence for accuracy.

      • Laura Schneider profile imageAUTHOR

        Laura Schneider 

        8 years ago from Minneapolis-St. Paul, Minnesota, USA

        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

      • profile image

        Earl Hemminger 

        8 years ago

        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.

      working

      This website uses cookies

      As a user in the EEA, your approval is needed on a few things. To provide a better website experience, turbofuture.com uses cookies (and other similar technologies) and may collect, process, and share personal data. Please choose which areas of our service you consent to our doing so.

      For more information on managing or withdrawing consents and how we handle data, visit our Privacy Policy at: https://turbofuture.com/privacy-policy#gdpr

      Show Details
      Necessary
      HubPages Device IDThis is used to identify particular browsers or devices when the access the service, and is used for security reasons.
      LoginThis is necessary to sign in to the HubPages Service.
      Google RecaptchaThis is used to prevent bots and spam. (Privacy Policy)
      AkismetThis is used to detect comment spam. (Privacy Policy)
      HubPages Google AnalyticsThis is used to provide data on traffic to our website, all personally identifyable data is anonymized. (Privacy Policy)
      HubPages Traffic PixelThis is used to collect data on traffic to articles and other pages on our site. Unless you are signed in to a HubPages account, all personally identifiable information is anonymized.
      Amazon Web ServicesThis is a cloud services platform that we used to host our service. (Privacy Policy)
      CloudflareThis is a cloud CDN service that we use to efficiently deliver files required for our service to operate such as javascript, cascading style sheets, images, and videos. (Privacy Policy)
      Google Hosted LibrariesJavascript software libraries such as jQuery are loaded at endpoints on the googleapis.com or gstatic.com domains, for performance and efficiency reasons. (Privacy Policy)
      Features
      Google Custom SearchThis is feature allows you to search the site. (Privacy Policy)
      Google MapsSome articles have Google Maps embedded in them. (Privacy Policy)
      Google ChartsThis is used to display charts and graphs on articles and the author center. (Privacy Policy)
      Google AdSense Host APIThis service allows you to sign up for or associate a Google AdSense account with HubPages, so that you can earn money from ads on your articles. No data is shared unless you engage with this feature. (Privacy Policy)
      Google YouTubeSome articles have YouTube videos embedded in them. (Privacy Policy)
      VimeoSome articles have Vimeo videos embedded in them. (Privacy Policy)
      PaypalThis is used for a registered author who enrolls in the HubPages Earnings program and requests to be paid via PayPal. No data is shared with Paypal unless you engage with this feature. (Privacy Policy)
      Facebook LoginYou can use this to streamline signing up for, or signing in to your Hubpages account. No data is shared with Facebook unless you engage with this feature. (Privacy Policy)
      MavenThis supports the Maven widget and search functionality. (Privacy Policy)
      Marketing
      Google AdSenseThis is an ad network. (Privacy Policy)
      Google DoubleClickGoogle provides ad serving technology and runs an ad network. (Privacy Policy)
      Index ExchangeThis is an ad network. (Privacy Policy)
      SovrnThis is an ad network. (Privacy Policy)
      Facebook AdsThis is an ad network. (Privacy Policy)
      Amazon Unified Ad MarketplaceThis is an ad network. (Privacy Policy)
      AppNexusThis is an ad network. (Privacy Policy)
      OpenxThis is an ad network. (Privacy Policy)
      Rubicon ProjectThis is an ad network. (Privacy Policy)
      TripleLiftThis is an ad network. (Privacy Policy)
      Say MediaWe partner with Say Media to deliver ad campaigns on our sites. (Privacy Policy)
      Remarketing PixelsWe may use remarketing pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to advertise the HubPages Service to people that have visited our sites.
      Conversion Tracking PixelsWe may use conversion tracking pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to identify when an advertisement has successfully resulted in the desired action, such as signing up for the HubPages Service or publishing an article on the HubPages Service.
      Statistics
      Author Google AnalyticsThis is used to provide traffic data and reports to the authors of articles on the HubPages Service. (Privacy Policy)
      ComscoreComScore is a media measurement and analytics company providing marketing data and analytics to enterprises, media and advertising agencies, and publishers. Non-consent will result in ComScore only processing obfuscated personal data. (Privacy Policy)
      Amazon Tracking PixelSome articles display amazon products as part of the Amazon Affiliate program, this pixel provides traffic statistics for those products (Privacy Policy)