Organizing a Userís Guide

9/7/00


Click here to start


Table of Contents

Organizing a Userís Guide

Reference guide versus userís guide

Userís guide

Reference guide versus 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

Writing Exercise

Userís Guide

Chapters (large-scale topics)

Types of chapters

ďAbout this DocumentĒ chapter

Introduction

Architectural overview

Main chapters

Writing Exercise

Userís Guide

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

Sections (mid-scale topics)

Define new concepts when critical to topic

Define terms when critical to topic

Userís Guide

Procedures, single concepts (small-scale topics)

Provide details

Are specific

Userís Guide

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 as tasks

Write headings that show the difference between similar topics

Format levels of headings differently

Tone

Use the second person (you)

Use the second person (you)

Use the second person (you)

Writing Exercise

Author: Karin Gallagher

Email: kgallag@rpbourret.com

Home Page: http://www.rpbourret.com/kgallag/index.htm