Should table of contents be organized by functionality or by menus and context-sensitive help topics?

Subject: Should table of contents be organized by functionality or by menus and context-sensitive help topics?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L List <techwr-l -at- lists -dot- techwr-l -dot- com>, karin -at- kgcreations -dot- com
Date: Wed, 26 Nov 2008 08:45:03 -0500

Karin wondered: <<Our technical writing team disagrees about how to
handle the TOC. Currently, our product's help file centers on context-
sensitive help and the TOC is based on the software's menus rather
than functions or procedures. These are not general menus like File
or View. To me, using the menu names to organize help makes it hard
for someone who is looking for procedures to find what they need. If
you don't know which feature to use to do something, how would you
know where to look in the TOC? (Okay maybe you would search, but the
search isn't that great either--that's another topic.) A couple of us
think the help TOC should list functions based on what the user needs
to do. It's okay to have context-sensitive topics and menus listed,
but not as the primary structure of the TOC.>>

This actually gets into the deeper question of how the document is
organized, since a traditional table of contents (TOC) must follow the
organization of the document. The reason for this is that the TOC
communicates the overall structure of the document, namely its
organization and how the parts fit together. This is similar to
providing a schema (mental model) of the document, which readers read
to understand how to use the document.

For example, a _reference_ manual tends to be organized to reflect the
structure of the software (since people are believed to only refer to
the manual when they encounter some problematic aspect software), thus
the TOC does too. Conversely, a _user_ manual is designed to support
how people use the software (not how the software uses them), and is
thus organized (or should be) around user goals, and secondarily
around the task clusters used to achieve those goals. The TOC then
reflects this organization.

If you're trying to meet both needs (reference and use) in the same
document, then the ideal solution is to provide both types of TOC.
This isn't at all unusual, and you'll even see documents with two or
more indexes at the back (e.g., an author index, a species index, a
keyword index) specifically because the authors chose to support two
or more types of use of the document. If your colleagues balk at the
notion of providing two TOCs, create a "stealth TOC": a table of
contents that doesn't look like one. For example, create a standard
reference-style TOC focused on the product's features, and start the
manual with a "how to use this product" section that resembles a mini-
tutorial and that provides an overview of a typical workflow. For
example, for a word processor, you'd start with creating a new
document and saving it, setting page size and margins and columns,
defining paragraph styles for titles and body text, and so on. Each
explanation would provide a high-level overview, combined with page
references to each of the sections of the document that provides
details.

FYI, I've used this approach very effectively in online help.

----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/books/eoe/onscreen-book.htm)

Print version: http://stores.lulu.com/store.php?fStoreID=1505747

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

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.
http://www.doctohelp.com

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-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


References:
Should table of contents be organized by functionality or by menus and context-sensitive help topics?: From: karin

Previous by Author: A philosophical tech writing question?
Next by Author: Re: What about OLD computers??
Previous by Thread: Re: Should table of contents be organized by functionality or by menusand context-sensitive help topics?
Next by Thread: RE: Telephone interviews


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


Sponsored Ads