Heading Hierarchy for a Complex Manual?

[Geoff Hart <ghart -at- videotron -dot- ca>]

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)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.