Editing Online Help

by Jean Hollis Weber
Published by WeberWoman's Wrevenge
155 pages
ISBN 0-9578419-0-6

Published October 2000

For students, writers, and editors who are developing online help for computer software, and for their managers and clients.

Supplements tool-specific instruction by presenting the basics of help content development, regardless of the operating system running the application, the type of help being produced, or the tools used to produce it.

In this book, you'll discover:

• The principles of planning, writing, and editing online help
• The ten most common complaints that users have with online help, the causes of the underlying problems, and ways to identify and cure those problems
• The eleven steps in the ideal help development process, their benefits, and the problems that arise when a step is left out
• What to include in the specifications, outline, and map for your help project
• Techniques for editing, reviewing, and testing the help

Full table of contents is below.

Available formats

The book is available in these formats: PDF, WinHelp 4, HTML Help, and browser-independent HTML (with and without frames).

You can download the book in as many formats as you choose, for one payment (US$8.00). Here are the file locations. When downloading a PDF, you may want to right-click on the file name and save the file rather than having it open in Acrobat Reader in your browser.

PDF formatted for US letter paper - 1250 KB http://www.jeanweber.com/ftp/OLHBkUS.pdf

PDF formatted for A4 paper - 1360 KB http://www.jeanweber.com/ftp/OLHBook.pdf

Microsoft HTML Help format - 670 KB http://www.jeanweber.com/ftp/olhbook.chm

WinHelp 4 format - 402 KB Zip file - unzips to 2.2 MB http://www.jeanweber.com/ftp/OLHwinh.zip

HTML format, using frames - 680 KB zipped file - unzip into its own directory http://www.jeanweber.com/ftp/OLHhtmfr.zip

HTML format, without frames - 675 KB zipped file - unzip into its own directory http://www.jeanweber.com/ftp/OLHhtmno.zip

Please don't forget to pay for your download.

Payment - special offer for members of the STC Online Information SIG

Downloaded copy US$7.00 or A$14.00 - $1 off regular price. Payment instructions are here: http://www.jeanweber.com/books/paymestc.htm

Contents of the book

Chapter 1 Planning an online help project
What is the editor's role in an online help project?
Why plan an online help project?
What process is used in an ideal help project?
    Step 1. Analyze the audience, plan the help project, and write the help plan
    Step 2. Develop high-level specifications
    Step 3. Develop detailed specifications
    Step 4. Perform a detailed task analysis
    Step 5. Build and evaluate a prototype help system
    Step 6. Develop an outline and map of the help project
    Step 7. Write, index, and edit the help topics
    Step 8. Review the help topics
    Step 9. Test the help
    Step 10. Release the help with the product
    Step 11. Evaluate the help and plan for improvements
How much time is required for editing online help?
What do you do when there's no plan and no time?

Chapter 2 Developing specifications
High-level specifications
    How will the online help fit in with other user documents?
    What type of help will best fit the application?
    How will the help be connected to the application?
    What media types are required?
    What tools will you need?
    What information types and levels are required?
    What topic types are required?
    How will the help windows (or pages) be presented?
    What navigation aids will be used?
    How will the help meet accessibility criteria?
Detailed specifications
    Reference materials
    Writing conventions
    Terminology
    Design and layout
    Help navigation scheme
    Task analysis
    Outline and map of help system
    Content of topic types

Chapter 3 Preparing for editing and testing
Deciding who does what, when
    How many reviews are needed, and when?
Organizing the flow of writing and editing work
Working with use cases and user scenarios
Developing lists of user tasks and test questions
Prototyping the help
Outlining and mapping the help project
Refining your prototype
Choosing methods for editing and reviewing

Chapter 4 Diagnosing common problems
1. I can't find what I'm looking for.
2. I can't figure out what's going on.
3. I can't figure out what will happen when I do something.
4. There's too much detail.
5. There's not enough detail.
6. I can't get to the help when I want it.
7. The program isn't working the way the help says it should.
8. Help tells me what the system does, but not how to use it.
9. I want a bigger picture of what this program can do.
10. The help is inconsistent and badly written and formatted.
Summary of diagnostics and cures for common help problems

Chapter 5 Editing the contents page and index
Editing a table of contents
    Quick diagnostics
    Things to look for when editing a contents page
    Example of a contents page with problems
    Examples of better contents pages
Editing indexes
    Quick diagnostics
    Things to look for when editing an index
    Example of an index with problems
    Example of a better index

Chapter 6 Editing for navigation and context
Diagnosing problems
Using browse sequences
    Editing browse sequences
Using cross-references and other links
    Editing cross-references and other links
Providing for reader-defined navigation
    Navigation pane
    Bookmarks and Favorites
    History list (WinHelp)
    Editing reader-defined navigation
Using visual aids such as icons or color
    Editing visual aids
Providing context information in the text
    Using words to provide context
    Telling users what to expect
    Providing the path to a topic
    Editing context information

Chapter 7 Catering for novices to experts
Diagnosing problems
    Not enough detail
    Too much detail
Some suggestions for fixing problems
Understanding user types
    Editing for user types
Using information types
    Editing for information types
Providing embedded help
    Editing embedded help
Providing assistance to novice users
    Editing wizards, coaches, show-me topics, and tutorials
Providing for user preferences
    Editing for users' preferences
Integrating the help system with other documents and systems
    Editing for integrated systems

Chapter 8 Linking from application to help
Diagnosing problems
Some suggestions for fixing problems
Providing context-sensitive help
    Specifying context numbers
    Editing context-sensitive help
Editing help for dynamic (variable) dialogs
Editing help for dialogs with multiple tabs

Chapter 9 Copyediting and production editing
Defining editorial roles
    Types and levels of edit
    Rule-based and analysis-based edits
Copyediting online help
    Using a style guide
    What belongs in a style guide?
    Company and project style guides
Production editing online help
    Finding and fixing display problems
    Graphics (blurry, wrong size, or unnecessary)
    Hotspots (links)
    Tables (display problems or too big)
    Bullets and numbered lists (display problems)
    Indentation (too much or inconsistent)
    Inconsistent help window sizes and placement

Appendix A Outlines and examples
Online help plan
High-level specifications
Detailed specificatons
Sample section on content of topic types

Appendix B Choosing help types and tools
Types of help
Tools

Appendix C For more information
Books and articles
Web sites and discussion lists

Appendix D Glossary

Appendix E Checklists

Index

Other books by Jean Hollis Weber

Taming Microsoft Word, February 2001
Electronic Editing, October 1999

---