Re: The cranky user: The importance of documentation

Subject: Re: The cranky user: The importance of documentation
From: Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM>
To: Technical Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 03 Dec 2008 16:19:45 +1100

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


References:
The cranky user: The importance of documentation: From: Cardimon, Craig
RE: The cranky user: The importance of documentation: From: Latella, Vincent

Previous by Author: Re: What's a "documentation specialist", as opposed to a writer?
Next by Author: Simplify, Simplify
Previous by Thread: RE: The cranky user: The importance of documentation
Next by Thread: Slight left turn on the path of Re: The cranky user: The importance of documentation


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


Sponsored Ads