Return to How to

Planning an online help project

by Jean Hollis Weber

This paper outlines some general principles you need to consider when planning an online help project and creating WinHelp files.

See also my paper titled Choosing and using help topics.

Some of the tasks described in this paper are the responsibility of the project leader; some are the responsibility of the writer or the editor; others may be a joint responsibility. In many cases, one person will be filling more than one of these roles.

Recommended background reading – online help guidelines

Microsoft Manual of Style for Technical Publications

Second Edition, Microsoft Press, 1998, ISBN 1556159390. This book is the public version of Microsoft’s style guide. It covers terminology related to the Windows interface and its use, as well as general aspects of Microsoft style, and includes a CD of the contents produced in WinHelp.

Microsoft Windows 95 Help Authoring Kit

Microsoft Press, 1995, ISBN 1556158920. Appendix A, “Windows 95 help style guidelines” covers many of the issues that technical writers need to consider when planning and writing online help.

Boggan, Scott, David Farkas and Joe Welinske, Developing Online Help for Windows

International Thompson Press, 1993 (Windows 3.1 edition, ISBN 850322198), 1996 (Windows 95 edition, ISBN 1850322112). This book is the definitive “how to” for creating WinHelp documents, and is an excellent introduction for anyone who wants to understand what goes on underneath the WinHelp authoring tool you use. It also contains some excellent information on writing online

help.

Deaton, Mary, and Cheryl Luckett Zubak, Designing Windows 95 Help: A Guide to Creating Online Documents

Que, 1996, ISBN 0789703629. This book is intended to help you understand how to create WinHelp documents; it focuses on the design aspects of WinHelp development. Chapters cover audience, window handling, navigation, graphics, multimedia, context-sensitive help, case studies and more.

Hackos, JoAnn and Dawn Stevens, Standards for Online Communication

John Wiley & Sons, 1997, ISBN 0-471-15695-7. Includes a CD-ROM containing a WinHelp file of the book, designed according to the principles taught in the book. Covers publishing information for Web pages as well as help systems.

Project leader’s planning tasks

The tasks described in this section would normally be done as part of the planning for the documentation project, and decisions would be recorded in the documentation plan.

Planning online help to fit in with other documents

Online help is usually one part of a documentation set for an application. When planning the help project, consider these questions in addition to other questions related to your user analysis:

  • Is this an in-house software product that will be supporting a set of procedures? Or it it a more general product that can be used for a variety of purposes?
  • Will the application have printed user documentation?
  • Will it have online documents (for example, a user’s guide or reference manual) in addition to the online help?
  • Will the end users be likely to have personal copies of any printed documentation?

You may decide that duplicating some or all of the information in different formats is the best way to serve the users’ needs, or you may decide that some information should be in one format only.

If you decide to duplicate information, and different writers are responsible for the different formats, you will need to closely coordinate the writing to ensure that confusion does not result.

Although you can easily create single-source files, from which you can create both printed documents (or online books) and online help, the results are frequently not as usable as they could be. A full discussion of this issue is outside the scope of this paper.

Do you need online help or an online book?

For in-house software products that will be supporting a set of procedures, users may be best served by having context-sensitive online help plus an online book of procedures or an online reference manual. You can link between these various files, so that users can choose the level of detail that best serves them at a particular time.

Do you need one help file or several files?

Many software products are modular – that is, customers may install or have access to a subset of the full product. If the various modules are provided as separate executable files, it will probably be best if the help is also provided in separate files, corresponding to the program files.

Another time when multiple files are required is when you’ve decided to provide other online information in addition to help.

Choosing and using a help authoring tool

Although you can produce a complex WinHelp system without using a help authoring tool, most writers do use a tool such as ForeHelp, RoboHelp or HDK (Hypertext Development Kit).

Planning for reviews and testing

You need to work with the software developers and testers to make sure everyone understands the types of reviews and testing required for online help, and who is doing which type of review or testing.

Technical reviews

Online help should be reviewed for technical accuracy by software developers and subject matter experts, just as printed documentation is reviewed; however, online help should be reviewed online, either in addition to a hard-copy review or in place of a hard-copy review. A major reason for this requirement is that popup and other linked material does not make sense on hard copy and it is not always possible to determine which popup is used in a particular situation.

Is the help helpful?

As with printed documentation, technically correct online help is not necessarily helpful to the user. A usability expert, business analyst or other suitably qualified person needs to review the help from the user’s perspective. Does it answer questions that a user is likely to ask in a given situation? Can the user find required information using the index or navigation tools provided? Are the cross-references and popups useful or confusing? In general, is the help helpful?

In addition to other editing tasks, the technical editor for the project is also responsible for reviewing the help for “helpfulness”.

Test of internal links

The documentation team is responsible for testing all internal links within the online help. Do they work? Do they link to the correct topics?

Test of external links

The test team is responsible for testing all external links – that is, the links between the application software and the help file. To assist the testers, you need to provide a map or table listing what help topic should be linked with each application window.

Planning ahead for HTML, Java or other conversions

WinHelp has been superceded by HTML-based help in Windows 98, although WinHelp files can be displayed using Windows 98. Some applications may continue to use WinHelp for some time; others may choose to switch to HTML-based help. HTML-based help is evolving rapidly. Currently at least two versions (Microsoft Internet Explorer and Netscape) are available; each version has some features that are not supported by the other version. In addition, Java-based help may be required for some application.

Plan ahead for the requirement to convert. Each of the three main help authoring tools provides a module that supports HTML-based help.

Writer’s planning tasks

The tasks describes in this section should be done in consultation with the project leader and the editor, to ensure consistency with other deliverables for the project.

Planning content and choosing which WinHelp features to use

If you are not an experienced WinHelp writer, or you know that someone else will be maintaining your file after you have written it, use only the basic features of Windows help rather than the more advanced features provided by the help authoring tools.

You can produce a very helpful file, with excellent navigation and indexing, without using any advanced features, and the programmers won’t have to include with the application any extra programs, files or DLLs to enable users to read the help.

Learn the basics first, and get the content, navigation and indexing correct, then – if you feel the users will benefit from the fancier features – add them later.

Some applications are developed for more than one Windows platform. If the online help will be used on multiple platforms, use only those features that are supported on all the platforms.

Developing an outline and map of the help project

You need to develop an outline and map of your help project, showing the relationship between the various help topics and the application windows, for these reasons:

  • One application window may be used for more than one user task.
  • More than one help topic may be needed for one application window.
  • One help topic may be re-usable for more than one application window.
  • The test team needs to know which help topic is intended to be called from each application window.
  • Whoever is testing the internal links (typically the technical editor or another documentation team member) needs to know what all the internal links are supposed to be.

Help authoring packages include various tools to assist you in developing an outline and map. Consult the documentation for the package you are using.

See also Choosing and using help topics.

Working with software developers

Time constraints may limit the way the online help is integrated with the software application. For example:

  • In Windows 3.1, when you press F1 or click a Help button, you can get help for the active window or help for the field or button where the “focus” is at the time, depending on how the help is attached to the program.
    For products aimed at non-technical users, I believe that providing help at the window (or dialog box) level first, rather than field level, is the most helpful approach. For products aimed at technical users, field-level help may be the starting point. On rush jobs, programmers may prefer to have all help start at the Table of Contents.

    You need to make sure that you and the programmers agree on how they are going to code their links, so that you can plan your help (especially the navigation). Windows 95 (WinHelp 4) provodes for both window-level help and “What’s this?” field-level help, but you still need to know how the programmers are going to code the links.

  • Developers may re-use windows in a variety of situations, but provide only one link from each window to the online help. The help must therefore be written so that it makes sense in all contexts. From a usability point of view, it is better for the programmers to make copies of the re-used window, with separate links to the help, so that individual help topics can be written for each situtation in which the window is used – but they may not do that. You need to know how these windows are being coded, so you can plan the help.
  • Some windows have tabbed pages. It is possible to link each page individually to a separate help topic, but it is easier for the programmers to link the whole window. Again, you need to know how these windows are being coded, so you can plan the help.

You need to work with the project leader to negotiate and record the decisions made regarding these programming issues.

Editor’s planning tasks

The editor needs to develop a project-specific style guide or style sheet to record specific decisions about the format, presentation and content of the help topics or other online documentation that will be provided for the project. Because the best mix of online help is different for different applications, this paper cannot tell you precisely what you need to do and how you need to do it. Work with the writer and the Project Leader when making the decisions.

Last updated 3 February 1999