Writing A User Manual (part 2)

See a sample table of contents for a user manual, and find out how to get the manual reviewed by others.

The Road Ahead

In the first part of this article, I introduced you to the process of creating a user manual, illustrating the groundwork you need to do prior to actually beginning work. In this concluding article, I’ll take you through the development process, demonstrating a sample TOC and giving you a few tips on the review and version management stages of the process.

Once you’ve got your stylesheet done, you’ve finally reached the point of production - where you actually start creating the document. Generally, the best way to go about it is to create the bare-bones structure (TOC), have it approved, fill in the peripheral information (overview, scope, conventions used, glossary) and then move in to the meat of the matter. This is also the time (ideally!) when the prototypes are finally ready for you to start working with.

The following is a generic user manual structure:

  1. Introduction
    • The product - introduce the product to the user.
    • The user manual
      • Scope/Purpose
      • Flow
      • Conventions
      • Glossary
  2. Installing the software (assuming it’s not a separate guide)
    • System requirements
      • Platform Support
    • Information/resources required in the process of installation
    • Installation steps

At this point there is usually a decision to be made about how to depict installation procedures for different platforms. The main criteriion here is how different the procedures are - if the steps are drastically different, you will have to explain the procedure separately for each platform. But if the steps are not very different, you could choose the most common platform as your base, and wherever the steps are different, indicate the steps for the different platforms as indented text.

  1. Using the software
    • Introduction
      • Purpose of the software
      • What it does and does not do (list the exact tasks)
      • User levels and the implications (segregate the user and admin level tasks)
    • Best configuration (for example, best viewed in 640x480 resolution)
    • Invoking the software
    • Interface elements
    • Steps to perform the required tasks
  2. Administration
    • Reiterate the administration level tasks
    • Segregate (if possible) into administration, maintenance and troubleshooting functions, and then get into explanations
    • Always lead in to a task with scenarios (for example, you need to shut down the server over the weekends and at the end of the day - here’s how…)
    • Also, try and bring out exceptional scenarios at the same time (to continue the above example, the administrator would not shut down the server over the weekend if there has been a request for remote access by one of the users)
  3. Troubleshooting
    • For each error condition describe: * What happens on the display * The error message displayed * What it means and what is the implication with respect to the attempted action (for example, the user will have to re-enter information) * Steps to take to rectify the error
  4. Appendix An appendix allows you to expound on peripheral information that would be detracting when given in the main body. Detailed diagrams, flow charts, or references to books/tutorials on related software could be included here.

Here are some quick tips to assist you in developing this structure:

  • Be visual: The most comforting thing for the user will be to see on screen what they’ve seen on the manual’s pages, or vice-versa. Try and use screen grabs and small schematic diagrams wherever appropriate.

  • Importance of relevant analogies: Essential if your software introduces concepts new to the user.

  • Use of transition words: “because”, “therefore” and “consequently” are powerful words when talking about cause-effect relationships that the user isn’t aware of.

Once you’re done with filling in the details, it’s time for a review.

Looking For Improvement

The review is a crucial process for any document, and more so for the user manual. You are dependent on the SMEs for verification of the technical information, on peer writers for editorial comments on structure and flow, technical support guys for evaluation of whether you’ve covered the most common support requests, and - of course! - a sample set of actual users to tell you whether it works.

But before you get to the point where you release drafts for review by these groups, you need to review the document yourself. Here’s a quick cheat sheet that assists in this process:

  1. Is all the information there? Have all the key terms been defined? Are instructions to cover all tasks there?

  2. Is the usage of paragraphs appropriate? Are they too long? On the other hand, guard against the paragraphs being so short and abrupt that the information seems unrelated.

  3. Does the flow make sense?

  4. Are the levels logical? Is the grouping together of modules sensible?

  5. Are the descriptive headings apt? Could there be a summary at the beginning and end of each section to guide the user better?

  6. Are there inconsistencies in usage of terms?

  7. Is the tone consistent throughout? Are you shifting from the first to the third person and back again?

  8. Are all topics covered to a consistent level of depth? Sometimes, at the time of writing, you may not have the same level of information on all topics covered (or you may just have been in a hurry to get the job done). This difference is very noticeable, and looks sloppy - watch out for it and fill in the consistent level of detail.

Once you’ve covered this ground, you can release the draft for review by the others involved.

Cheat Sheet

A thorough review needs a lot of commitment and time. You will need to make it easier for your reviewers by including quick cheat sheets stating what they should be looking for. An example cheat sheet for the SMEs would be:

  1. A technical review is not an editorial review.

  2. Focus on the technical facts to verify that the technology works as documented.

  3. Verify the technical accuracy of all procedural steps included in the document.

  4. Verify the technical accuracy of all screen captures in the document.

User reviews are a tad trickier than the others are because of the lack of resources. First, you may not have access to the actual users to review your document. And second, they may not really be motivated at that point to take the time to review your document. The workaround is to use your marketing and QA departments, and perhaps the people from the customer’s end who are involved in the project.

Once the reviews are in, you need to get down to implementing the changes suggested. One tip would be to start revision on a document only after all the review comments are in. Also, while we won’t get into the art of accepting feedback, you have to be in control of the changes that you agree to make. While you can change the information quite a bit at the time of the first review, you should try and restrict your changes to corrections only after the second review; structural changes this late in the process will throw you off.

Version Control

A characteristic of documentation is that if you notice even one inaccuracy in a document, it will put you off going through the rest of it. The gravity of this increases manifold when you’re talking about a user who’s looking to this document to understand your software. Ensuring that your manual reflects the latest version of the software is crucial, and this is where tying the document version number with that of the software comes in.

Another consideration here is version nomenclature. You could tie this in with the software, using x.y nomenclature that has x changing with every baseline change and y changing for every intermediate release of the document. Also, when you revise the document, you should record the reason/description of the change in the document’s revision log.

Putting The Package Together

With all of this behind you, you will finally be ready to release the manual. The following frills will complete the package:

  1. Cover page
    • The name of the software should be written in accordance with the brand decided.
    • The version number of the software should be clearly stated.
    • The name of the developer with address and contact numbers.
  2. Table of contents
    • The topics should be linked to the matter inside.

  3. Notifications for proprietorship and confidentiality

  4. Headers and footers
    • Headers could include the project name and version number of the document.
    • Footers can have the page numbers and a short confidentiality notice.

It might also be a good idea to include a feedback form as the last page, as your users will probably get back to you with suggestions. This will be especially useful if there is a second phase of development for the software.

And that’s about it. If you’d like to learn more about the technical writing process in general, here are some links you might find useful.

Developing documentation without a tech writer, at http://builder.com.com/article.jhtml;jsessionid=HIXSTKI530XXVTQQABUCFEY?id=u 00320020510gcn02.htm&vf=ra

The Seven Deadly Assumptions of Technical Communication, at http://www.williamrice.com/techcomm/sevenassumptions/7assump1.html#Assumption1

Online Technical Writing - An Online Textbook at http://www.io.com/~hcexres/tcm1603/acchtml/acctoc.html

Word Home Page, at http://lists.raycomm.com/techwhirl/magazine/technical/wordhomepage.html

Happy writing!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!

This article was first published on 31 Dec 2002.