How to create online help that meets your users’ needs
by Jean Hollis Weber
published by Hentzenwerke
NOTE: Free copy of PDF available here.
December 2005: This book has won the Best of Show award in the
Technical Publications Competition conducted by the Australia Chapter of the Society for Technical Communication. May 2006: This book has won an award of Distinguished in the International Technical Publications Competition conducted by the Society for Technical Communication.
This book was written for students, writers, and editors who are developing online help for computer software, and for their managers and clients.
It 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 10 most common complaints that users have with online help, the causes of the underlying problems, and ways to avoid those problems
- The 11 steps in the ideal help development process, their benefits, and the problems that arise when a step is left out
- Techniques for planning, writing, editing, reviewing, and testing online help
- Sample plans and specifications for your help project
Available in printed or PDF format, with supplementary materials on the book’s Web site. For more information on prices and how to order, see http://www.hentzenwerke.com/catalog/ithh.htm.
Note: This book replaces Editing Online Help (published in October 2000), which is no longer available. Is the Help Helpful? is completely revised and updated.
Table of Contents
Chapter 1: Planning an Online Help Project
Online help is as much a part of the user interface as windows, dialog boxes, or Web pages. It must be planned and designed as part of the project, with similar consideration for users’ requirements. This chapter describes an ideal planning process, the roles of the people involved in producing online help, the time required, and the work sequence for help development.
Chapter 2: Analyzing Audiences and Tasks
Online help must be designed to meet its users’ needs, which may be quite different from the needs of the software developers. Most users want task-oriented help; some users may also want function-oriented help. Developers typically want function-oriented help. This chapter describes techniques for analyzing audiences and their tasks, including developing user profiles and scenarios.
Chapter 3: Developing Specifications
High-level specifications should include the help format, information types, topic types, navigation and accessibility aids, media types, and other presentation factors; how the help is linked to the application; how the help coordinates with any other documentation for the software; and the tools to be used in developing the help. Detailed specifications get into the specifics of writing conventions, terminology, design and layout, the navigation scheme, and the content of various topic types; they usually include a style guide for the project.
Chapter 4: Prototyping the Help System
You can build a prototype of your help system in several stages. In the early, high-level concept and design prototype, be sure to include examples of all relevant navigational aids, topic types, and links between topics. Later, as you outline and map the help project, you can build a more detailed contents prototype.
Chapter 5: Avoiding Common Problems
To develop truly helpful online help, writers need to think like potential users, include information to answer their questions at an appropriate level of detail, and make the information easy to find. This chapter describes the 10 most common complaints that users have with online help, the underlying problems that lead to these complaints, and ways to identify the problems and avoid or fix them.
Chapter 6: Producing the Table of Contents and Index
Readers use the table of contents or the index to look up information not immediately associated with the visible window or dialog box, when they want answers to "can I?" or "how do I?" or "where is?" questions. This chapter describes ways to make the table of contents and index useful from the readers’ point of view, so they can find information quickly and easily.
Chapter 7: Providing Navigation and Context
Navigation includes all the ways for readers to move around in a help system and find the information they want. Context helps readers keep track of where they are, how they got there, and what happens next. This chapter describes some methods for providing navigation and context.
Chapter 8: Meeting the Needs of Novices to Experts
Readers often complain that the online help contains too little information; it gives only the obvious instructions or it describes the fields but gives no clue how to use them. Other readers complain that the help contains too much information; they can’t find the answer to their questions in all the details. This chapter describes some common problems and suggests ways you can provide help that meets the needs of a range of users, at the right level of detail for each of them.
Chapter 9: Linking from Application to Help
Linking from the application to the help requires cooperation with programmers, as well as consideration of users’ needs. This chapter describes different ways of linking, the pros and cons of each, and the type of information that writers and programmers need to share to make the system work.
Chapter 10: Copyediting and Production Editing
Copyediting should go beyond grammar and punctuation to revising the language used and the presentation of the material, to ensure it meets the requirements in the specifications and style guide. Production editing is done at the end of the development phase, checking that the topics in the help system display as they should, and the navigation works properly.
Chapter 11: Usability Testing on a Budget
If you avoid usability testing your help system because you think it takes too long and costs too much, read this chapter to find out how to find 80% of problems quickly and inexpensively.
Appendix A: Sample Plans and Specifications
Get going quickly with these sample plans and specifications. Fill in the blanks in the files on the website.
Appendix B: Help Types and Tools
A summary of some common types of help, their pros and cons, and the tools you can use to produce them. Covers Windows, Macintosh, and Linux environments.
Appendix C: For More Information
Books and Web pages with more details on topics covered in this book.
Appendix D: Glossary
Terms used in this book.
Appendix E: Checklists
Reminders of what you need to do at each step of the help planning and development cycle.
Last updated 18 December 2015