Re: Deeply nested headings

[kcronin -at- daleen -dot- com]

Is the software you're documenting as complex as, say, Photoshop?

If so, I'd suggest that you look at some of the aftermarket books written
for products like this, and use them as examples to follow. None of the
ones on my shelf (and I'm a bit of a collector) have anywhere near that
number of heading levels.

I don't doubt that the product you're working with is complex. What I
suggest is that maybe it's less important to stress the hierarchical
relationships of the topics you're documenting.

What these books usually DO have is a good TOC and a good index. You can
make it just as easy (or in this case, I'd guess even easier) for the user
to find the information they need by having a robust TOC. This
necessitates that you name your headings carefully, to make them as
descriptive as possible.

I've done a lot of manuals and documents that did not have indexes (not my
choice - I was doing what I was ordered to do), and in those cases I tried
to assist the user with very descriptive headings that would be picked up
in the TOC. These headings tended to be a bit wordy at times, but you
could skim the TOC and quickly find what you needed.

What kind of numbering do you use to enforce this hierarchy? Is the
numbering 8 layers deep? If so, I'd be surprised if users found it really
helpful to be asked to look up I.4.A.5.ii.14.c.02, or something similar.

Another way to break up such deeply nested headings is to break them up at
a higher level. Books can have sections. Sections can have chapters, etc.
But once again this begins to veer into a more complex construction than
many users will want to deal with.

Looking at my Photoshop and Illustrator books, it seems that they have
allowed many potentially nested topics to simply stand on their own as
"hierarchically equal" - an arrangement that might not jibe with YOUR
knowledge of the product's features and their relationships to one
another, but one which makes it very easy for the uninitiated to find the
information they seek.

Hope this is helpful.


-Keith Cronin
________________________

So many sig lines, so little pertinent content...

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.