Heading Hierarchy for a Complex Manual?

Subject: Heading Hierarchy for a Complex Manual?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 07 Nov 2005 12:47:20 -0500

Kirk Turner reports: <<I am in the process of editing a very long and complex manual. I am writing the style guide, and I am on the section on heading hierarchy. Except for the unwieldy APA guidelines, I haven't found any guidance on the subject.>>

That's probably because heading structures is something of an art, and there doesn't seem to have been much research done to support effective recommendations on structures.

<<I have the Chicago Manual of Style guidelines, but I don't see any examples or suggestions that relate to what I am doing.>>

Chicago isn't the best guide for this kind of work. It provides very good advice on language use in general, but doesn't provide specialized advice on the issues we face in creating documentation or online help. There are two better sources for this: I like Sun's "Read me first", but others like Microsoft's style guide. I tend to stay away from Microsoft's guide because I've seen some discouraging critiques of their editorial advice; ymmv.

<<I used what was in the Chicago Manual of Style anyway and came up with these levels of heading...>>

I'm somewhat uncomfortable with your suggestion of using five levels of headings. The general rule of thumb that I've seen is that heading levels should be limited to 3; this is standard for many science journals, for example. I haven't seen any good research to support this (and would appreciate details from anyone who has), but it's certainly true that George Miller's research on short-term memory applies here: typical readers can hold 7 plus or minus 2 chunks of information in their working memory, and your 5 headings falls at the lower end of that limit.

This means that some readers will have considerable difficulty understanding where they are in the document hierarchy (i.e., how the current level 5 head relates to the four previous heading levels, thus, "where am I in this hierarchy?"). The real meaning of Miller's research is simple: the more you expect people to hold in their heads, the more difficult a time they'll have doing so. Reduce the heading complexity and you make it easier for everyone--even for the rocket scientists who have no trouble with a 9-level hierarchy.

There are lots of ways to simplify heading hierarchies. One obvious one is to make level 1 the title of the window rather than the first line of text within the window. This immediately cuts one level out of the heading hierarchy. Another approach is to combine heading levels. Let's say you have "Printing" as your heading 1, with "Producing paper" and "Producing PDF" as the first level 2 heads. Why not combine them to produce two new topics: "Printing on paper" and "Printing to PDF"? (Choose better examples, of course.)

Another option is to use tables judiciously. Sometimes it's possible to use one of your low-level headings as a subheading within a table. The presence of the table visually separates the table contents from the surrounding text; the subheadings within the table facilitate navigation within the table. Think "information mapping" and you'll get the idea.

And then there's the "remember we're working online and can create popups if necessary" approach. For example, what if your level four headings formed a concise summary of the steps in a procedure, and clicking on any step would pop up a secondary window containing details of that step? This provides a quick summary for those who only need a reminder of the sequence, but more details are available at the click of a button (via the secondary window) for anyone who needs more detail. Plus, the overall sequence remains visible in the background, behind the secondary window, so readers never need to remember how to return to it; they simply close the secondary window and there it is!

Don't forget "you are here" information: Although people can use the "back" button in their help browser to step back through a series of topics, making this explicit in the first line of the window is more effective. Consider, for example, "breadcrumbs", with each crumb hyperlinked to the appropriate topic:

You are here: Help for Module A --> Help for submodule A1 --> Help for subsubmodule A1.1
(replace those with actual useful titles).

<<(this is for an online manual): . The first level heading will be Verdana, 14 pt., upper and lower case, underlined and centered. . The second level will be Verdana, 14 pt., centered, uppercase and lowercase. . The third level will be Verdana, 12 pt., flush left, uppercase and lowercase and underlined. . The fourth level heading will be Verdana, 12 pt., one tab from left and capitalized as it would be in a sentence. . The fifth level of heading will be Verdana 12 pt., two tabs from the left and underlined. End this heading with a period and begin the first sentence of the body text for this heading on the same line as the heading. >>

Apart from the number of headings, I have a few additional concerns: First, you should generally avoid using underlining, since this is (by convention) the cue that something is a hyperlink. Second, by the time you've got two tabs away from the left margin, you're beginning to run out of space to actually present text. Third, there doesn't seem to be much visual distinction between the heading levels; for example, your first two levels look very similar once you get rid of the underline.

Here are several thoughts on how you can make the heading levels more distinct:

- Instead of underlining, "box" the headings. This box can be a rule above and below the heading, or a color bar that surrounds the heading; so long a the lower rule doesn't come too close to the text, it won't be seen as an underline. You can create color bars most easily by placing the heading in a one-line table and setting the background color for that table cell.

- Speaking of color, you didn't mention whether the headings are colored. I don't recommend that you go crazy with color, but it's easy to pick a color compatible with the window background color and use that for the headings. The color should be dark enough for contrast with the background but visually distinct from the body text font (usually black). I've used dark green and dark blue successfully on an ivory (off white) background.

- Consider using the body text font (e.g., Times New Roman) or its color instead of Verdana for the 4th and 5th heading levels. Color defines the level 1-3 heads; the lack of color defines in-text heading levels 4 and 5.

<<Maybe it is just fear of failure clouding my vision. Any guidance would be greatly appreciated.>>

Have you tried your design on your audience? There's nothing quite like the approval of your readers to eliminate that ol' fear of failure. <g>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Heading Hierarchy for a Complex Manual: From: Kirk Turner

Previous by Author: Project 11: developing a new ISO standard for managers of user documentation.
Next by Author: Dual-use font?
Previous by Thread: Re: Heading Hierarchy for a Complex Manual
Next by Thread: Re: Heading Hierarchy for a Complex Manual?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads