RE: Should table of contents be organized by functionality or by menusand context-sensitive help topics?

["Gordon McLean" <gordon -dot- mclean -at- ciboodle -dot- com>]

Can't you offer both?

A TOC entry only points at the content, so you could have two pointers (or
more) to one piece of content?

That way you can allow for different mental models (as you've described).

Gordon 

-----Original Message-----
From: techwr-l-bounces+gordon -dot- mclean=ciboodle -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+gordon -dot- mclean=ciboodle -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of karin -at- kgcreations -dot- com
Sent: 25 November 2008 19:01
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Should table of contents be organized by functionality or by
menusand context-sensitive help topics?

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.

The third writer believes the TOC has to be based context sensitive help and
menus, and insists that is the norm everywhere. But when I look at the help
files for the programs I use, the TOCs are function based. A few help files
have an interface or menus section, but they don't organize topics by the
software's menus.

Here is an example:

Context sensitive:

MENU
--System Setup
-----XXXX
-----XXXX
-----XXXX
--Administration
-----Application Setup (These are not the same as system setup) --Reports
-----Report Formats -----Report Selector


Function:

Setup
--Application
--XXX
--XXX
--XXX
Reports
--Report Formats
--Using the Report Selector (or Creating Reports)



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

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 gordon -dot- mclean -at- ciboodle -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/gordon.mclean%40ciboodle.
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

___________________________________________________________________
Sword Ciboodle Ltd (a company registered in Scotland with
registered number SC143434 and whose registered office is at
India of Inchinnan, Renfrewshire, UK, PA4 9LH) is part of the Sword
Group of companies.

This email (and any attachments) is intended for the named
recipient(s) and is private and confidential. If it is not for you, please
inform us and then delete it. If you are not the intended recipient(s),
the use, disclosure, copying or distribution of any information
contained within this email is prohibited. Messages to and from us
may be monitored. If the content is not about the business of the
Sword Group then the message is neither from nor sanctioned by
us.

Internet communications are not secure. You should scan this
message and any attachments for viruses. Under no circumstances
do we accept liability for any loss or damage which may result from
your receipt of this email or any attachment.
___________________________________________________________________

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

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