Re: Indexing of reference manual? (Take II)

Subject: Re: Indexing of reference manual? (Take II)
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Oct 2001 13:59:40 -0400

"Hart, Geoff" wrote:
>
> Martina Sasnauskaite provided more information: <<what if the TOC of the
> reference manual is structured alphabetically?>>
>
> Then it's an index. <g> Seriously, though, if it simply follows the topics
> in alphabetical order, then that's the appropriate structure, but it still
> doesn't solve the reader's problem: "How do I find a specific topic when I
> don't know what name the developers gave it?" The answer is, of course, to
> come up with my own name for it and see whether that name is in the index.
> If not, I try another name, and another, until I give up and ask the woman
> down the hall who's our local expert in this software.
>
> <<Then what do I have to do? To rewrite the TOC and to add in the index all
> the names of the buttons, such like - OK, Cancel? What should be included? I
> think the main target of the reference manual is to describe the GUI?>>

One possibility is to do a permuted index. Likely some form of search
engine is a better answer, but a permuted index is likely easier, and may
be worth doing even if you have search as well.

For an example of such an index, automatically generated from HTML headers
in a bunch of files, see:

http://www.freeswan.org/freeswan_trees/freeswan-1.5/doc/perm.html.html

The software that built those (quick and dirty, not production quality)
is in the FreeS/WAN distribution, and under a GPL license. I'm no longer
generating that index for the current release; look at 1.5 or so.

These were a standard feature of Unix documentation 20 years ago, and
there were standard utilities to build them. The Unix permuted index
was built from the one-line descriptions in the "name" section of the
man pages, e.g "grep - find patterns in text files" This practice seems
to have been dropped somewhere along the line.

What a permuted index does is build an index line for every content
word (not "the", "of", etc.) in a title or description. e.g. take the
sentence "Eric Ray runs the tech writer mailing list". This gives,
among others, an index line with "writer" as the key word:

Eric Ray runs the tech writer mailing list

All the index entries get sorted by keyword. Then, if all you remember
about this list is the word "writer", you look for that in the index
and find:

My favorite writer is Robert Anton Wilson
Eric Ray runs the tech writer mailing list
HP CD writer model 666

If all you remembered was "Ray", you might be looking at:

Ray Bradbury wrote Farenheit 451
Eric Ray runs the tech writer mailing list
sting rays are poisonous fish

Either way, you could find the appropriate entry.

> As noted above, you need to be able to think like a user of the manual: What
> are they looking for? (Not the OK button, but the task that you get the
> software to do when you press OK.) What names will they use to look for it?
> (Think synonyms.) If you can't answer either question yourself, then you
> need to ask it to people who can provide answers: your audience, of course,
> but also tech support staff, trainers, sales staff, etc.

Yes.

Some years back, I wrote some docs on microcomputer software that was to
be used mainly by people with only IBM mainframe experience. Somewhat to
my surprise, the feature of those docs that got more glowing praise than
any other was the index, mainly because I'd included synonyms from
mainframe land, things like "DASD: see hard disk".

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


References:
RE: Indexing of reference manual? (Take II): From: Hart, Geoff

Previous by Author: Re: Dual-monitor system with Word?
Next by Author: Re: Glossary
Previous by Thread: RE: Indexing of reference manual? (Take II)
Next by Thread: Line breaks in pdf?


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


Sponsored Ads