|

Longman / Prentice Hall

English

My Instructor Resource Center :  Log in or request access

Writing Software Documentation: A Task-Oriented Approach (Part of the Allyn & Bacon Series in Technical Communication), 2/E
Thomas T. BarkerTexas Tech University

ISBN-10: 0321103289
ISBN-13:  9780321103284

Publisher:  Longman
Copyright:  2003
Format:  Paper; 496 pp
Published:  10/01/2002
Status: Instock


Suggested retail price: $87.33
Buy from myPearsonStore



Part of the Allyn & Bacon series in technical communication, Writing Software Documentation features a step-by-step strategy to writing and describing procedures.

This task-oriented book is designed to support both college students taking a course and professionals working in the field. Teaching apparatus includes complete programs for students to work on and a full set of project tracking forms, as well as a broad range of examples including Windows-style pages and screens and award-winning examples from STC competitions.

  • Offers a step-by-step process for analyzing users and designing task-oriented documents.
  • Checklists in each chapter provide convenient summaries for keeping organized and on track.
  • Abundant exercise work helps students develop the skills they need to write good documentation.
  • Flexible chapter organization allows for selective reading depending on whether the reader is doing a specific project or reading to understand broader concepts.
  • Examples in each chapter offer specific and detailed explorations of document elements relevant to the chapter topic.
  • Guidelines sections in each chapter break sometimes complex tasks into discrete steps.
  • Practice sections in each chapter offer cases for application of concepts learned and help provide discussion material.
  • Extensive instructor's manual includes chapter quizzes, overhead masters, additional exercises, and sample syllabi.
  • Re-organized and simplified approach now emphasizes tutorials, procedures, and reference manuals in a more concise, and accessible style throughout.
  • New coverage of Web-based design techniques (HTML, JavaScript, multi-media) and an increased focus on writing online documents (especially HTML and help documents).
  • Complete set of planning forms for use with a companion help authoring tool.
  • Now includes a new section on writing for multicultural and multilingual users.
  • New emphasis on techniques for addressing complex user tasks.
  • Expanded treatment of editing for design and illustrations.
  • Improved coverage of indexing and keyword searching.
  • Updated, award-winning examples.

Each chapter begins with “Examples,” and “Guidelines,” and concludes “Glossary,” “Checklist,” and “Practice/Problem Solving”.

1. Understanding Task Orientation.

1. Emphasize Problem-Solving.

2. Provide Task-Oriented Organization.

3. Encourage User Control of Information.

4. Orient Pages Semantically.

5. Facilitate Both Routine and Complex Tasks.

6. Design for Users.

7. Facilitate Communication Tasks.

8. Conducting Usability Tests.

9. Support Cognitive Processing.



Discussion.

The Principles of Software Documentation.

A Definition of Task Orientation.

The Theory Behind Task Orientation.

Tutorial Documentation.

Procedural Documentation.

Reference Documentation.

The Processes of Software Documentation.

I. The Forms of Software Documentation.

2. Writing to Teach—Tutorials.

1. Identify User Actions You Need to Support.

2. State Objectives as Real-World Performance.

3. Choose the Right Type of Tutorial.

4. Present Skills in a Logical, Cumulative Structure.

5. Offer Highly Specific Instructions.

6. Give Practice and Feedback at Each Skill Level.

7. Test Your Tutorial.

Discussion.

Designing Tutorials.

Tutorial Users Need Special Care.

The Elaborative Approach.

The Minimalist Approach.

3. Writing to Guide—Procedures.

1. Relate the Task to Meaningful Workplace Activities.

2. Determine How Much Information Your User Needs.

3. Choose the Appropriate Procedural Format.

4. Follow a Rhythm of Exposition.

5. Test All Procedures for Accuracy.

Discussion.

What Constitutes a Procedure?

How Does a Procedure Work?

4. Writing to Support—Reference.

1. Choose the Right Form of Reference.

2. Decide What to Include.

3. Establish Pattern.

4. Organize the Reference Section.

5. Show How to Use the Reference Information.

Discussion.

Understanding the Reference User.

Understanding a Reference Entry.

II. The Process of Software Documentation.

5. Analyzing Your Users.

1. Choose Users Carefully.

2. Anticipate Transfer of Learning: Study Before and After Tasks.

3. Research Professional Behaviors.

4. Write User Cases.

5. Plan Interviews Carefully.

6. Involve Users in All Phases of the Project.

7. Identify Document Goals.

8. Tie the User Analysis to Documentation Features.

Discussion

What Does Use Mean?

What You Want to Know About Users.

Tasks the User Will Perform with the Program.

The User's Informational Needs.

The User's Work Motivations.

Range of Computer Experience: Novice, Experienced, Expert.

Extent of Knowledge of Subject Matter of the Program.

The Workplace Environment: User Communities.

Users' Learning Preferences.

Usage Patterns: Regular, Casual, Intermittent.

6. Planning and Writing Your Documents.

1. Start the Project.

2. Design the Documents.

3. Perform the User Analysis.

4. Plan the Documentation Project.

5. Write the Alpha Draft.

6. Conduct Reviews and Tests.

7. Revise and Edit.

8. Write a Final Draft.

9. Conduct a Field Evaluation.

Discussion.

Team Structures.

Kinds of Development Documents.

Processes.

The Documentation Plan.

Reviewing the Documentation Plan.

An Outline for a Documentation Plan.

7. Getting Useful Reviews.

1. Review the Document Objectives from the Documentation Plan.

2. Determine the Type of Review Needed.

3. Establish a Review Schedule.

4. Plan the Reviews.

5. Write a Cover Letter with Questions for Reviewers.

6. Prepare Feedback Materials for Reviewers.

Discussion.

Reviewing Differs from Testing.

Reviewing Differs from Editing.

The Purpose of Reviews.

Reviewing throughout the Documentation Process.

Reviewers as Partners.

Negotiate Conflict Diplomatically.

Do a User Walkthrough.

Review Form.

8. Conducting Usability Tests.

1. Decide When to Test.

2. Select the Test Points.

3. Choose the Type of Test.

4. Set Performances and Learning Objectives.

5. Select Testers and Evaluators.

6. Prepare the Test Materials.

7. Set Up the Test Environment.

8. Record Information Accurately.

9. Interpret the Data.

10. Incorporate the Feedback.

11. Tie Testing to Document Goals.

12. Do Some Pilot Testing.

13. Make the Test Objective.

Discussion

What Is Testing?

The Importance of User Testing as Part of User-Driven Design.

The Advantages of Field Testing.

Methods of Field Testing that Emphasize Task Issues.

How to Interpret Test Data.

9. Editing and Fine Tuning.

1. Establish Project Guidelines.

2. Understand the Types of Editing.

3. Plan Your Editing Tasks.

4. Develop the Appropriate Editing Forms.

5. Conduct Editing Sessions.

Discussion.

Editing Graphics.

Writing Versus Editing.

Writing for Cross-Cultural Readers.

Editing for Translation.

How Do You Know What's Correct?

Take a Constructive Attitude.

Consult Standard Style Guides.

III. The Tools of Software Documentation.

10. Designing for Task Orientation.

1. Create a Table of Contents.

2. Match the User Analysis with Information Design Strategies.

3. Acknowledge Production Constraints in Document Design.

4. Test and Review the Design.

5. Follow a Design Process for Online Help.

Discussion.

The Design Problem.

Accommodating Groups of Users.

Matching the User's Problem—Solving Methods.

A Design Guide for Printed Documentation.

Navigation.

Cross—References.

Running Headers and Footers.

Solutions to the Design Problem for Online Documentation.

11. Laying Out Pages and Screens.

1. Review the User Analysis.

2. Create Page Grids.

3. Define the Page Grid Using Styles.

4. Draw Thumbnail Sketches.

5. Set Up Pages and Styles in Your Word Processor.

6. Determine the Layout of Help Documents.

Discussion.

Designing Communication Spaces.

How to Look at Pages and Screens.

Common Page Designs.

The Elements of Page Design.

Common Screen Designs.

The Elements of Screen Design.

Designing Type.

Helping People Recognize Words.

Design Advice.

Building Patterns with Type.

The Idea of Body Text.

Non-Body Text.

12. Getting the Language Right.

1. Write About Actions Rather than Functions.

2. Revise for the Active Voice.

3. Revise to Keep Writing Simple.

4. Revise to Build Parallel Structures.

5. Add Operational Overviews.

Discussion.

How Do We Process Language?

Performance-Oriented Language.

How Do We Remember and Learn?

Style Problems in Software Documentation.

13. Using Graphics Effectively.

1. Identify Needs for Graphics by Your Users.

2. Set Graphics Styles.

3. Revise and Edit.

4. Revise for Typography.

Discussion.

Showing How Tools Apply to the Workplace.

Show Results of Software Operations.

Present Overviews to Integrate Software with Workplace Activities.

Suggest Functions and Uses.

Make the Abstract Concrete Through Metaphors.

14. Designing Indexes.

1. Plan Your Indexing Strategy.

2. Decide What to Index.

3. Identify the Level of Detail.

4. Decide on Phrasing and Format.

5. Edit and Proofread.

Discussion.

Why an Index?

Online Index Versus Print Index Versus Keywords.

Automatic Indexing Software Programs.

Indexing with Search Engines.

Tools for Indexers.

Endnotes.

Credits.

Index.

Companion Website, 2/E
Barker
©2003 | Longman | On-line Supplement | Instock
ISBN-10: 032113219X | ISBN-13: 9780321132192
URLhttp://www.ablongman.com/barker2e


Instructor's Manual, 2/E
Barker
©2003 | Longman | Paper | Instock
ISBN-10: 0321122534 | ISBN-13: 9780321122537
  View Downloadable Files



Essential Study Card for Grammar and Documentation
Longman
©2007 | Longman | Study Card; 10 pp | Instock
ISBN-10: 0321463137 | ISBN-13: 9780321463135


InterWrite PRS RF (Personal Response System)
InterWrite PRS & Allyn & Bacon/Longman
©2005 | Longman | Electronic Supplement | Instock
ISBN-10: 0205436951 | ISBN-13: 9780205436958


ResearchNavigator.com Guide: English (Valuepack item only)
Branscomb & Trim
©2007 | Longman | Paper; 80 pp | Instock
ISBN-10: 0321496019 | ISBN-13: 9780321496010


iClicker Classroom Response System
iClicker & Allyn & Bacon/Longman
©2008 | Longman | Electronic Supplement | Instock
ISBN-10: 0205594506 | ISBN-13: 9780205594504


For Software Documentation

MyTechCommLab Student Access Code Card (Standalone)
Pearson
©2006 | Longman | Access Code Card | Instock
ISBN-10: 0321463595 | ISBN-13: 9780321463593
URLhttp://www.mytechcommlab.com


For Technical Communication - Advanced

MyTechCommLab Student Access Code Card (Standalone)
Pearson
©2006 | Longman | Access Code Card | Instock
ISBN-10: 0321463595 | ISBN-13: 9780321463593
URLhttp://www.mytechcommlab.com


Companion Website, 2/E
Barker
©2003 | Longman | On-line Supplement | Instock
ISBN-10: 032113219X | ISBN-13: 9780321132192
URLhttp://www.ablongman.com/barker2e


Pearson Higher Education offers special pricing when you choose to package your text with other student resources. If you're interested in creating a cost-saving package for your students contact your Pearson Higher Education representative.