Designing a Readable User Manual

Documentation design includes not only the structural issues of the overall organization of information that I discussed in my last article, but also the layout of each page. Page layout is an important aspect of readability. A page full of straight text in a small typeface is not inviting. Since many people do not like to read documentation at all, the least you can do is to ensure that each page is easy to read.

In deciding your layout, you must ensure that you leave sufficient "white space." "White space" refers to the portions of a page that are blank, no matter what color you are using. Large margins, spaces between sections, and easy-to-read fonts are factors to address. You should design each page to be pleasing to the eye. Trying to fit as much information as possible on each page does not aid your reader. Look at the manuals you have at work and at home. Which are the most appealing and easy to read? The ones that are full of single-spaced text with small margins, or the ones with more "white space" and less text on each page? Of course, the documents with less text on each page are easier to read.

You must decide how your layout will handle headings, tables, sample screens, warning messages, shortcut tips, etc. Each of these elements gives you the opportunity to increase readability by adding variety and interest to your document. Make sure you have lots of headings to help steer readers to the information they need. You will want add space between each section and make the headings eye-catching by using boldface type or a different font. Large margins can be used for short descriptive headings or shortcut tips. (Be sure you still leave plenty of "white space.") To highlight warnings or hints you may want to use italics or put the text in a box. You can insert sample screens that relate to the text which will help you explain a feature and increase the visual appeal of your pages.

Once you decide how to format each of these elements, make sure you write a document specification to record your decisions. Other design considerations include numbering of tables and sample screens, deciding on page headers and footers, and distinguishing user input from system prompts. You should include all of these in your specifications.

You can use your layout and specifications to increase readability in other ways. Using tables is an effective way to present information that may be difficult to explain in paragraph form. Tables are good when you want to show, for example, how different settings can affect output. You can clearly display each option and the associated result as in the example below.

*If you set Report* to:**	The result is:
week	weekly report of revenues
month	monthly report of revenues
year	last 12 months of revenues

Bulleted or numbered lists are helpful when you are writing long lists or instructions. Rather than writing the list or steps required to perform a function in paragraph form, write them in a numbered (or bulleted) list. Consider the following examples.

Example 1

First, select the text you want to move. Next, click Cut. Then, place the insertion point where you want to paste the text. Last, click Paste.

Example 2

1. Select the text you want to move.

2. Click Cut.

3. Move the insertion point where you want to paste the text.

4. Click Paste.

Which of these examples is easier to read and understand? Not only are numbered lists and tables easier to follow, they also break up the text. You will want your specifications to include when to use numbers or bullets or some other symbol for step-by-step instructions and long lists.

To gain the full benefit from your specifications, you should be sure that all writers and editors have a copy. This will ensure consistency, an important issue when more than one person will be writing or editing your documentation. Clearly defining and consistently applying these techniques will increase the readability of any type of documentation.