TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
"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:
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.
