Last update Dec29/19W3C//Dtd html 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> Master Style Guide: Chapter 6

Chapter 6
Online documentation

Online documentation should resemble hard copy documentation and therefore should follow similar standards. For specific information about web site design and styles, refer to Chapter 5, "Developing web sites."

Structure

Online documentation is set up similarly to that of a hard copy document. Topics are ordered, introduced, broken down into parts, and concluded with a departure point, which ties all the parts together and leads into the next section. Unlike hard copy documentation, you must rely more on visual cues and reinforcing information the user received earlier in the document.

Content

Your content should be well-structured, like a book. Once a concept has been established, build on it. Do not repeat information the user already knows, unless you are using it to reinforce. If you ask the user to select a menu button in the first few screens, you do not have to assert later that those buttons are interactive.

Use concrete examples to explain more abstract subjects and show a range of examples to define a complex subject.

Organization

More sophisticated tutorials may have to consider some design factors: Menus, database retrieval, context sensitivity, navigation, and full text search. Before outlining your online documentation, identify the user, and determine the user's familiarity with the subject.

Consider how the user will
- Enter and exit the document.
- Read the entire document.
- Scan or page through the document.
- Step through menus.
- Move through directories.
- Retrieve specific topics (for example, by name, number, or keyword).
- Browse among topics.
Describe topics from general to specific, chunking information into topics and subtopics.
Draw attention to transitions between sections, clearly indicating the end and beginning of a topic and making connections between concepts.
Reinforce information provided previously and make sure this information is provided at points where non-sequential reading may occur.
Define words and terms when you introduce them.
List items sequentially in the order that they appear.
Use navigational aids, such as headings, to reinforce the user's location within the document.
Display objects to represent navigational controls, such as menu or page-down buttons. Highlight the next likely step for the user (for example, the PgDn button).
Explain delays and error messages. Because online documentation is interactive, display and explain an error message immediately after it occurs.

Visual format

When you create online screens, make active use of white space and keep paragraphs shorter than you normally would for hard copy text.

Label all displays-screens, menus, and buttons-in the online document.
Make the user aware of his or her location in the online document by displaying visual cues for the
- Command being executed
- Menu currently displayed
- Most recently selected menu option
- Field containing the cursor
- Prompt currently displayed
- Icon pointed to by the cursor
Make sure when showing overlapping windows that all windows' titles are displayed. Be aware that overlapping implies a hierarchical relationship to the user, prioritizing the windows by suggesting the window on top has greater immediacy.
Use arrows, not lines, to show direction.

Font usage

It is easier for the human eye to read serif fonts on paper (such as the Times font that this document uses for text) but easier to read sans serif fonts on video screens (such as the Arial Black font that this document uses for headers). When creating online documentation, use sans serif fonts for body text.

html documentation should use a list like

<font FACE="Helvetica", "Arial", "Geneva">

to specify the sans serif fonts to use in the desired order.

Using color

Although black and white is most legible, colors can improve meaning and functionality, provided that you don't use more than 3 or 4 distinct colors. Additional colors will impede reading speed. Make sure the colors work with your display.

Consider the following:

Attention getting--Use from best to worst: orange, red, blue, black, green, yellow, violet, and gray.
Background--Use cool colors which recede into the page: blue, dark green, violet. Avoid warm colors which advance out from the page: red, orange.
Preferability--Use red, blue, and green. Avoid violet, orange, and gray.
Visibility--Use white, yellow, or green. Avoid red and blue.

Do not rely on a color only to convey a particular distinction; color associations may vary culturally. Refer to Table 4 for common psychological associations with color.

Table 4
Psychological associations with color

Color Psychological associations
Red Stop, danger, fire, anger, warmth, passion, excitement, negative cash balance
Blue Police, navy, water, coolness, sky, serenity, fidelity
Green Go, growth, trees, country spring, restfulness, youth, freshness, money
Yellow Caution, sunlight, cheerfulness, heat, life, light
White Hospitals, sterile, purity, innocence, peace, calm
Gray Somberness, dignity, quietness, age, wisdom, gravity

Color	Psychological associations
Red	Stop, danger, fire, anger, warmth, passion, excitement, negative cash balance
Blue	Police, navy, water, coolness, sky, serenity, fidelity
Green	Go, growth, trees, country spring, restfulness, youth, freshness, money
Yellow	Caution, sunlight, cheerfulness, heat, life, light
White	Hospitals, sterile, purity, innocence, peace, calm
Gray	Somberness, dignity, quietness, age, wisdom, gravity

Jump to table of contents

Back to Chapter 5, "Developing web sites"

Onward to Chapter 7, "Creating presentations"