Re: The cranky user: The importance of documentation

[Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM>]

Latella, Vincent wrote:
> 
> The author makes an interesting point regarding indexes, although I'd
> like to hear his opinion regarding *when* adding one is warranted. 
> 
> I'm assuming he'd say that it's somehow tied to document length and/or
> complexity; whereas a two-page quick reference wouldn't benefit greatly
> from an index, a 200 page manual clearly would.  
> 
> Regardless, surely he doesn't advocate the inclusion of indexes on
> *everything,* does he?
> 
> I just wonder if there's a rule of thumb that can be applied here. I'd
> wager to say that not all of us create documents that are "undermined"
> by their lack of indexes.  
> 

Our style guide recommends indexes for all documents that
have 20 or more pages. The recommended length is one page
of index entries for every 20 pages of text, or about one
index entry for every 100 words of text for standard content,
and double that for dense technical material (one page for
every 10 pages of text). We don't often achieve this ideal
of a comprehensive index length, though, I must admit.

-- Janice

***********************************************************
Janice Gelb          | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com  | this message is the return address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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