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

[voxwoman <voxwoman -at- gmail -dot- com>]

I second this suggestion.
-Wendy


On Wed, Nov 26, 2008 at 7:47 AM, Gordon McLean
<gordon -dot- mclean -at- ciboodle -dot- com>wrote:

> 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.mclean <techwr-l-bounces%2Bgordon.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 voxwoman -at- gmail -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/voxwoman%40gmail.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
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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