TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Debbie Hemstreet wondered: <<When there are a lot of books in a Help
file, and many subbooks as well... if you work according to strict
printed documentation logic, headings can go as deep as 5 levels.>>
That's pretty nasty. I find that I rapidly lose track of my overall
position within the hierarchy once it grows beyond 3 levels,
particularly for complex materials. "Limit headings to three levels"
is common advice in a great many style guides, and for a good reason:
the more effort we must spend figuring out where we are in the
hierarchy, the less brainpower remains to figure out the actual task-
related information. (Basically, this relates to the burden placed on
working memory.)
So it's always worthwhile trying to simplify the heading hierarchy
wherever possible. You may not be able to get it down to three levels,
but every little bit helps. One standard approach is to make the
position in the hierarchy explicit rather than forcing readers to hold
it in working memory, and that leads to a couple suggestions that are
easy to implement.
<<I know this is not idea, but here is the scenario: A large Internet
Software package (The whole big book) Seven main modules (Seven sub-
books) Up to 10 main functions and procedures, with their own sets of
requirements, etc, as well as how to for a screen (up to 10 subbooks)>>
One possible solution: create a separate help file for each module,
and move the module title into the title of the Help window. That's
one fewer level right there, bringing you down from five to four.
There are various tricks to provide access to the other modules. For
example, consider using breadcrumbs at the top of each window as a
navigation aid:
You are here: Master list of modules --> Current module's name
The "master list" text would be a clickable hyperlink back to a table
of contents for the seven modules. Clearly, this could be expanded by
adding a third level of hyperlinks. This provides constant and
explicit reinforcement of the user's position within the heading
hierarchy, eliminating the need to hold that information in working
memory.
Alternatively, you could try this as a "tabbed" interface, with all
seven module names appearing across the top of the window as clickable
links. Same basic effect, but more efficient than forcing readers to
return to the table of contents for modules. You'll see this approach
used effectively in the navigation bars of most modern Web sites.
Next you have the problem of adding a level for sub-books: this can
sometimes be solved by merging two levels of heading, thereby
eliminating another level of headings and bringing us to three. For
example, you could use the module name as a prefix for each function
in the top-level headings:
Printing module: Page layout functions
Printing module: Selecting a printer on the network
etc.
Repeating the overall title within the headings again provides an
explicit reminder intead of requiring the reader to remember "Printing
module" while they're five levels deep in the hierarchy.
<<I sure do miss working on a team where we can discuss all the
different options and play with ideas before making a design
decision...>>
Fortunately you have the world's largest virtual team right here. Best
of all, you don't have to share your chocolate stash. <g>
------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing: http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
