RE: Quality Indexes

[Gregory Leblanc <GLeblanc cu-portland edu>]

> -----Original Message-----
> From: Kenny Graunke [mailto:kwg@teleport.com]
> Sent: Wednesday, June 07, 2000 10:55 AM
> To: gnome-doc-list@gnome.org
> Subject: Quality Indexes
> 
> Hello all,
> 
> Have any of you noticed that computer generated indexes are 
> really bad?
> Some of Microsoft's products (at least older ones) did this, and, for
> example, everything ended up under `MS-DOS', and was 
> generally not very
> useful. I'm not sure just who does HP printer manuals, but I've heard
> that they have everything under `Printer'. How many of you would think
> to look under Printer?
> 
> I don't think a computer can ever really do as good of a job as a real
> person. You can always tell the difference. My suggestion is 
> that we do
> indexes manually. It would be more work. A good, easy to use index is
> essential for larger documents. I think it would really improve the
> overall quality of our documentation. Quality documentation with good
> indexes will certainly help "sell" GNOME. (No, I don't mean "sell" as
> in just monetarily.)

I don't know how the indexing works on other things, but for DocBook it's
mostly done in markup, with an <indexterm> tag.  Check out the DocBook: TDG
for some pretty decent examples.  There's a perl script called
collateindex.pl that creates an index out of these terms.  I can't imagine a
computer generating an "index" as the term is used in Windows help.  Now,
the search function can certainly be done by the computer, and probably
should be, since it's a full text indexing function.
	Greg