Home arrow Practices arrow Page 2 - Writing A User Manual (part 2)

Looking For Improvement - Practices

In this concluding article, take a look at a sample table ofcontents for a user manual, understand the importance of having yourwork reviewed by peers, and find out how to handle document versionmanagement.

  1. Writing A User Manual (part 2)
  2. Looking For Improvement
  3. Cheat Sheet
  4. Version Control
  5. Putting The Package Together
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 20
January 03, 2003

print this article


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.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: