"Great Technical Writing" Series


 

Home | Contact | Site Map

Navigation:  Home -> Reading Room -> Great Tech Writing Series -> This Article


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. 

Newspaper & Advertisement Headings Are Aimed at Getting Reader to Read Further

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:

Rather than tease, headings should:

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:

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. 1.  ...

  2. 2.  ...

  3. 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 Material

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 Guidelines Regarding Headings

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:

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.

Resources

Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary).  He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker.  For the past seven years he has been researching and creating resources to help organizations create great User Documents. 

Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.

Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.

You may copy and distribute this article freely.  However you must keep the entire article and Resources sections intact, with no changes, additions, or deletions.

Copyright 2007, Igetitnow! Training, Inc.