Great Technical Writing: User Document Headings Should Be Guideposts, Not Advertisements

OVERVIEW

Most heading are designed to entice us to read further. Headings in User Documents should enable your Reader to decide whether or not to continue reading that section. Use effective headings to make it easy for your Reader to access and understand your User Document.

MOST HEADINGS ARE FOCUSED ON GETTING THE READER TO READ MORE

Usually, these headings provide just enough information or use clever wording to tease the Reader to continue. Many User Document authors incorrectly do the same. Users do not want to read the User Manual, and they should only be encouraged to read text if it is of relevance to them. They should not be teased into reading irrelevant material.

Here are some examples of teaser-type headings:


"TIP:"

The Reader does not know if the tip is relevant or not, and thus is forced to read the text to make a decision.


"Headings Can Discourage Reading"

A teaser if ever there was one. Since it implies a contradiction, its goal is to get the Reader to read. If it's not important for every Reader to read this information, then you have misled your Readers.

Rather than tease, headings should:


Enable your Reader to decide whether or not to read the text, or


Provide enough information so that your Reader can skip the text

HEADINGS SHOULD HELP YOUR READER TO DECIDE WHETHER OR NOT TO READ ON

A good heading provides the information that your Reader needs to decide whether or not to read the text that follows it. It should not use any clever wording to entice the Reader to read unnecessary material.

Let's improve on the previous "teaser" examples:


"TIP: USE WORD PROCESSOR STYLES"

Your Reader will skip this if he/she is already using styles to format their word processor documents.


"Headings Can Provide Enough Information to Discourage Reading"

If your Reader understands what this means, then he/she can skip the material.

HEADINGS CAN PROVIDE ENOUGH INFORMATION TO DISCOURAGE READING

A good example is the step-by-step instruction. Headings should be part of any series of (step-by-step) instructions. Each heading tells the Reader what he/she will be doing in the following instruction steps. The Reader can decide to read or skip the text, based on the heading and his/her capabilities. For example:

Delete the CONFIG.STP File by Following These Steps:

1....

2....

3.... etc

A Reader who knows how to find and delete the CONFIG.STP file can use the information in the heading alone to perform the desired task. A Reader who doesn't know how to perform the deletion will follow the more detailed steps.

In this situation, the heading helps the Reader self-select based on his/her skills.

DESCRIPTIVE HEADINGS PROVIDE GOOD ACCESS TO THE TEXT

Descriptive headings (that accurately describe the text that follows) enable your Readers to find desired information on the page. When skimming a page, Readers focus on the headings. It is much easier to browse headings than to browse text.

SOME USEFUL HEADING GUIDELINES


Don't Mix Information Between Headings

All of the information that follows a heading until the next heading should relate to the heading that introduces the text. Don't add information irrelevant to the heading in the text following that heading. Doing so makes it harder for your Reader to find material in your User Document, and confuses your Reader when reading the text ("why is this here?").

If necessary, add additional headings.


Consider Using More Headings in Your Writing

By having more headings, you reap the following benefits:


There will be more "white space" in your document. These blank areas make your writing more inviting and easier to read.


You provide more guideposts to the information. These additional guideposts make topics easier to find in your writing, and sets the tone for the text to follow.


Headings Should Stand Out from the Text

Make headings larger, bolder, set off from the plain text in the document. This will enable your Reader to easily find and use the headings. If you have no control over the font of the headings, put them in all capital letters.


Denote Headings with Your Word Processor's "Styles".

Use your word processor "styles" or equivalent to denote headings. The alternative is to manually format the headings to make them stand out.

By using "styles," all headings of a particular level will look the same; you can easily change appearance of all of the headings at once, and you can easily create Tables of Contents.

THE BOTTOM LINE

Users do not want to read User Documentation. By using headings that help your Reader to decide whether or not to read the text that follows, you make his/her reading experience more effective.

Headings are a powerful access mechanism for any kind of writing don't squander this power.