Organizing a User’s Guide
Reference guide versus user’s guide
User’s guide
Concepts versus tasks
Write your documentation by tasks user does
Good documentation is task-driven
Writing Exercise
User’s Guide
Write an outline
Develop a hierarchy
Organize into large-, mid-, and small-scale topics
Function of large-, mid-, and small-scale topics
Topics at same level have equal importance
Develop no more than four levels of topics
Too many topic levels
Write topics as if users read them in order
Chapters (large-scale topics)
Types of chapters
“About this Document” chapter
Introduction
Architectural overview
Main chapters
Sections (mid-scale topics)
Give context to tasks and concepts
Define task or concept and when to use it
Define parts of a task or concept
Compare low-level tasks and concepts
Define order of procedures
Define new concepts when critical to topic
Define terms when critical to topic
Procedures, single concepts (small-scale topics)
Provide details
Are specific
For all topics
Use examples and graphics to illustrate tasks and concepts
Use real-life and code examples
Real-life examples
Code examples
Use an example that does something
Introduce example
Use screenshots and diagrams
Write useful headings for topics
Write descriptive headings
Write headings as tasks
Write headings that show the difference between similar topics
Format levels of headings differently
Tone
Use the second person (you)
Email: kgallag@rpbourret.com
Home Page: http://www.rpbourret.com/kgallag/index.htm