Progress
Help Development
Guide


Topic Style Guidelines

In planning your help topics, keep them as brief as possible. To keep topics modular, avoid lengthy introductory paragraphs, complex concepts and comparisons, transitional passages, and text-based cross-references. Many of the techniques that make for good printed material do not translate well into online help.

Instead of writing long help topics that must be scrolled into view while the user reads the text, try to limit each help topic to the amount of information that can fit within its window type. Use hypertext features to lead the user to more information on related subjects.

Whether you are working with previously written material or developing your help topics from scratch, it is important to edit your text rigorously and to format it for maximum readability online. Table 2–4 summarizes some basic style guidelines.

Table 2–4: Help Topic Style Guidelines 
Design Element
Guideline
Amount of text
Use a minimum of text. Reading speed of online text is generally 30% slower than printed text.
Paragraph length and white space
Reading online text is harder than reading a printed page. Keep paragraphs as short as possible. Use margins, inter-paragraph spacing, and other white space liberally.
Fonts and text highlighting
A sans serif typeface such as Arial or Helvetica improves readability. Body text should be at least 8 points. Avoid using all uppercase text, multiple fonts, or too many colors.
Graphics and icons
Although help lets you place graphics anywhere in a help topic, graphics can dramatically increase the size of your help file. Use graphics sparingly to aid comprehension. Avoid using graphics for decoration.
Design consistency
To reduce possible confusion and to build end-user confidence in the information your help files provide, be sure to use type, spacing, colors, terminology, hypertext links, and graphical design elements consistently.

The remaining two chapters explain how to create topic, contents, and project files, and how to compile them to create a help project.

The instructions in these chapters assume that you are using only the utilities that are provided with your Progress product, plus MS-Word and accessories that are supplied with Windows. Note that there are many help authoring tools available that can save you time by automating many of the tasks described in this chapter.

For complete reference information on all aspects of Windows help development, see the Help Author’s Guide , an online help file associated with Help Workshop, \Program Files\Progress\bin\hcw.hlp. Help Workshop, \Program Files\Progress\bin\hcw.exe, is a Microsoft utility provided with Progress.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095