Logo         Community
The Company
Your Account
Contact Us
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.

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

4. 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)

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

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

How to do Everything with PHP & MySQL
How to do Everything with PHP & MySQL, the best-selling book by Melonfire, explains how to take full advantage of PHP's built-in support for MySQL and link the results of database queries to Web pages. You'll get full details on PHP programming and MySQL database development, and then you'll learn to use these two cutting-edge technologies together. Easy-to-follow sample applications include a PHP online shopping cart, a MySQL order tracking system, and a PHP/MySQL news publishing system.

Read more, or grab your copy now!

more like this print this article  next page
In trog...
Logging With PHP
Building A Quick-And-Dirty PHP/MySQL Publishing System
Output Buffering With PHP
Date/Time Processing With PHP
Creating Web Calendars With The PEAR Calendar Class
In the hitg report...
Crime Scenes
Animal Attraction
Lord Of The Strings
In boombox...
Patience - George Michael
Think Tank - Blur
My Private Nation - Train
In colophon...
Hostage - Robert Crais
The Dead Heart - Douglas Kennedy
Right As Rain - George Pelecanos
In cut!...
American Chai
The Core
Find out how you can use this article on your own Web site!

Copyright © 1998-2018 Melonfire. All rights reserved
Terms and Conditions | Feedback