4.3: Page Design

Learning Objective

Upon completion of this chapter, readers will be able to:

1. Explain and apply design guidelines for heading and list use in technical documents.
2. Explain and apply design guidelines for including notices in technical documents.
3. Explain and apply design guidelines for table and figure use in technical documents.
4. Explain and apply design guidelines for text highlighting and alignment in technical documents.
5. Explain and apply design guidelines for font and color in technical documents.

Common Page Design

Page design means different things to different people, but here it will mean the use of typography and formatting such as you see in professionally-designed documents.

Our focus here is technical documentation, which implies modest, functional design.

For even more detail than you see here, consult these two standard industry resources:

• Sun Technical Pubs. Read Me First! Any recent edition. Prentice Hall.
• Microsoft Corporation. Microsoft Manual of Style for Technical Publications. Any recent edition. Microsoft Press.

Headings

The following presents some of the standard guidelines on headings.

• Insert plenty of headings, perhaps one heading for every two to three paragraphs. Avoid overkill, though: lots of headings with only one or two sentences per heading does not work.
• Indicate a heading's level through design. Use type size, type style, color, boldness, italicization, and alignment to make a heading's level obvious. ("Levels" of headings are like levels in an outline: Level 1 corresponds to the large, capitalized roman numerals; Level 2 to the capital letters; Level 3 to the arabic numerals; Level 4 to the lower-case roman numerals; and so on.)
• Limit the levels of heading. Most documents only need three or fewer levels of heading; more levels can confuse your readers.
• Describe the sections' contents with specific language. Vague headings like "Technical Background" don't tell anybody anything.
• Use parallel phrasing. Parallel headings tell readers if the sections are similar to each other.
• Avoid "lone headings." If you have one heading, you should use a second. It's the same concept as having an "A" without a "B" or a "1" without a "2" in outlines.
• Avoid "stacked headings" (two or more consecutive headings without text in between).
• Don't use a pronoun to refer to a heading. If you have a heading like "Configuring the Software," don't follow it with a sentence like "This next phase..."
• Consider the "hanging-head" format for major headings. In this design, some or all of the headings are on the left margin, while all text is indented one to two inches. This format will make headings stand out more and reduce the main text's line length.
• Consider using "run-in" headings for your lowest-level headings. In this design, the heading "runs into" the beginning of a paragraph and ends with a period. You can use some combination of boldness, italics, or color for these headings. This format avoids the problem of lower-level headings blending in with each other.

Lists

Lists are useful tools for emphasizing important points, enabling readers to scan text rapidly, and providing more white space. The following presents some of the standard guidelines on lists.

• Use numbered lists to show sequence, order, or hierarchy. Use bulleted lists for items that can appear in any order.
• Use standard numbered- and bulleted-list formats. They are built into word-processing programs, and HTML has ordered- and unordered-list tags.
• Use parallel phrasing for lists' contents.
• Introduce all lists with lead-in text; don't start a list immediately after a heading.
• Unless your organization's style overrides, punctuate list items with a period only if they are complete sentences or have embedded dependent clauses.
• Be consistent with using initial caps or lower-case letters on the first words of list items.
• Use different symbols for the second levels of nested lists. For numbered lists, use lowercase letters. For bulleted lists, use bolded en dashes or empty-centered circles. In either case, make sure that nested items align to thetext of the previous level.
• Avoid using too many lists or overstuffing lists. Seven to ten items is generally about the maximum number of items.

Notices

Notices are specially-formatted chunks of text that alert readers to special points, exceptions, potential problems, or danger. The following presents some of the standard guidelines for notices.

• Make notices more prominent and noticeable as they become more severe. Consider using this standard hierarchy:
  • "Danger" for situations that could involve severe injury or death
  • "Warning" for situations that could involve minor injury
  • "Caution" for situations that could involve equipment damage, data loss, or a threat to a procedure's success
  • "Note" for exceptions or situations that do not require the preceding tags
• Whatever notice design you use, avoid using long strings of bold text, italics, capital letters, or combinations of these. In addition to telling readers to do or not do something, explain three things:
  • under what conditions they should use the notice
  • what will happen if they ignore the notice
  • how to recover if they ignore the notice
• Make notices' text succinct, but not at the expense of clear writing. Avoid telegraphic writing style (omitting articles like a, an, the) in notices.
• In numbered lists, align notices to the text of the list items they apply to. Put notices in two places:
  • before the step in which the potential problem exists
  • at the beginning of the entire procedure

Figures

Figures are illustrations, drawings, schematics, photos, and other visual materials. The following presents some of the standard guidelines on figures.

• In the text before each figure appears, provide a cross-reference to the figure.
• If you include a label and caption, place them below each figure.
• Omit labels and captions if they have no vital function and are not needed (for example, in instructions when the figures are closely related to the individual steps).

Tables

Tables are like lists, which were discussed previously, but are more structured and formal. In your text, look for repeating pairs, triplets, or quadruplets of items that can be formatted as tables. For example, a series of terms and definitions is a classic use for tables. The following presents some of the standard guidelines for tables.

• Look for repeating groups of items in your text that you can format as tables.
• In the text before each table appears, provide a cross-reference to the table.
• Include a table title unless the content of the table is utterly obvious and the table contains few items. Place the table title above the table, or make it the top row of the table.
• Use column and row headings (or both) to define the contents of the columns and rows. Consider highlighting these headings.
• Left-align text columns (unless the contents are simple alphabetic characters). Left-align text columns with their headings.
• Right-align or decimal-align numerical data, and center it under its heading.
• Put standard measurement units (ft, mm, gal.) in the column or row heading rather than with each item in the column or row.
• Briefly discuss the main trend in the table—what you want readers to notice.

Highlighting

Software documentation typically uses a lot of highlighting. Highlighting here refers to bold text, italics, alternate fonts, capital letters, quotation marks, and other typographical tricks used to call attention to text. The following presents some standard guidelines for highlighting.

• Establish a plan for using highlighting, and apply it consistently
• Use highlighting for specific, functional reasons. Avoid too much highlighting, and avoid complicated highlighting schemes.
• Consider using this fairly standard highlighting scheme:
  • For simple emphasis, use italics.
  • Use bold for commands, on-screen buttons and menu options.
  • Use italics for variables for which users must supply their own words.
  • Use an alternate font for text displayed on screen or text that users must type in.
  • For screen and field names, use the capitalization style shown on the screen but no other highlighting.
  • Use an initial cap for key names but no other highlighting.
  • For extended emphasis, use the notice format.

Margins, Indentation, & Alignment

As mentioned in the section on headings, you may wish to indent main text one to two inches while leaving headings on the left margins. This style does two things: it makes the headings stand out, and it shortens the main text's line length.

Fonts & Color

Here are some suggestions concerning fonts and color:

• Limit the number of main fonts that appear in a document to two. For example, you might use Arial for headings and Times New Roman for body text.
• Use only one alternate font, at most two. For example, you might use Arial for headings, Times New Roman for body text, and Courier New for text that users will see onscreen or that users must type in.
• If you use color, use it minimally and consistently. For example, if you have black text on a white background, you might select another color for headings. You might use that same color for figure and table titles as well as the tags for notices (the actual "Note," "Warning," "Caution," and "Danger" labels on notices).
• Avoid unusual combinations of background and text colors. For example, purple or red text on a black background is unreadable. Stick with black text on a white or gray background unless there is a strong, functional reason for some other color combination.