Goals of Documentation ITSW 1410, Presentation Media Software Instructor: Glenda H. Easter

Writing 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 (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 Users 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 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 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 Users Manual (Continued)  Ease of Reading –Make use of white space. –Write at a 5th grade level (short, simple sentences, characters per line.) –Avoid unnecessary jargon

Editing 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)  Mechanical Style Edit - “English” abbreviations and spelling  Substantive Edit - content  Language Edit - take out contractions, etc.

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