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

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

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