[Tutor] Advice required: Documentation Writing / Sofware Testing

[Michael Powe]

On Fri, Dec 20, 2002 at 03:27:13PM -0700, Bob Gailer wrote:

> At 11:35 AM 12/20/2002 -0800, Terry Carroll wrote:

[ ... ]

> >Also, consider indexing a subject, not only under the term you use, but
> >also under the term someone who doesn't yet know your terminology mught
> >use.  For example, if you have a function trim() that removes blanks,
> >consider "stripping blanks: see trim()."  If you have a command FIND that
> >finds a string in a piece of text, consider "locating a string: see FIND".

> >This is especially important when you can't know what to look under unless
> >you already know the answer you're looking up.  If my question is "how do
> >I specify formatting a string," I want to be able to look up "format" or
> >"string", not "%s".
> 
> YES YES.

I find it curious how badly indexed most technical books are.
indexing ought properly to be an automated procedure, in which a list
of index terms is prepared and then the text is formatted for
processing to build the index.  but it seems that most books are not
done this way.  even o'reilly, which processes and prints most if not
all of its books in unix, generally has horrible indexing.  but both
TeX and troff provide index-building functions!  it is a common
occurrence to look up an item in the index, check the text; and then
later find an unindexed reference to the term that contained
information i needed.  sometimes, it almost seems like the indexing
procedure consists of somebody reading through the text and
arbitrarily deciding which terms on a page or in a section to index.

mp