Chapter 4: Document Design

4.3: Page Design

By: David McMurrey and Jonathan Arnett

Objectives


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

  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:

Headings

The following presents some of the standard guidelines on headings.

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.

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.

Figures

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

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.

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.

Margins, Indentation, and 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: