Goals of DocumentationGoals of Documentation

ITSW 1410, Presentation Media Software

Instructor: Glenda H. Easter

Writing an Effective ManualWriting an Effective Manual

In writing an effective manual, you should ensure that you do the following:– Provide a good introduction. This Introduction should

include:• Rational of product of book -- what it is about.• Audience description• Format• How to use book• Background and history• Chapter preview, reviews, etc.• Acknowledgment

Writing an Effective Manual Writing an Effective Manual (Continued)(Continued)

You should ensure that you do the following:– Include a Chapter Review, if possible.

• Tell them what you’re going to tell them.• Discuss the concepts to be learned.• List educational objectives.

– Your Key Concepts should include:• Essential data• Steps on how to do something• How to use equipment• Definitions• Legends

Three Main Design Goals of a Three Main Design Goals of a Users ManualUsers Manual

Ease of Navigation– Organize and label chapters, sections according to user goals.– Table of contents should present high-level overview not

exhaustive list.– Provide an index with entries for both user goals and tasks

and operation names.– Separate different types of information

• Motivational (information that explains why its useful and why you use it.

• Conceptual (what feature does and results)• Procedural (what are the steps)• Examples (Make information more concrete)

Three Main Design Goals of a Three Main Design Goals of a Users Manual (Continued)Users Manual (Continued)

Ease of Learning– Provide a foundation and build on it--“Hook ‘Um.”

– Teach in layers and small units - mini lessons.

– Teach in logical sequence - avoid forward references

– Give examples

– Provide illustrations

– Make consistent use of locational and visual use.

– Avoid abstract formal notation - brackets

– Use analogies

Three Main Design Goals of a Three Main Design Goals of a Users Manual (Continued)Users Manual (Continued)

Ease of Learning (Continued):– Lead users to draw inferences (basic information and

draw conclusions: general to specific).– Avoid anthropomorphism - “The Computer Knows”– Provide a section on troubleshooting– List error messages with detailed messages and

explanations on how to fix and get around error.– Document should be consistent in style and

terminology with on-line help, prompts, instructions and messages.

Three Main Design Goals of a Three Main Design Goals of a Users Manual (Continued)Users Manual (Continued)

Ease of Reading– Make use of white space.– Write at a 5th grade level (short, simple

sentences, 50-55 characters per line.)– Avoid unnecessary jargon

Editing DocumentsEditing Documents

Coordination Edit - get people, budget, money and schedules.

Copy Clarification Edit - Clarification Edit instructions, typeset and graphics

Policy Edit - company standards and procedures. Integrity Edit - all cross-references are clear and

accurate Format Edit

Editing Documents (Continued)Editing Documents (Continued)

Mechanical Style Edit - “English” abbreviations and spelling

Substantive Edit - content Language Edit - take out contractions, etc.

Review DocumentsReview Documents

Choose the reviewers and time to review. Show reviewers how to review (proofreader

symbols, etc.) Give feedback to reviews (thanks for time,

how they did).