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.
McLauchlan, Kevin wrote:
> On Behalf Of Ned Bedinger said:
> [...]
>> I agree, given a typical help file or electronic documentation, full
>> text searching (FTS) is the only tool of value. Indexes these days,
>> ... are not developed systematically or thoroughly.
>
> An index often gives me some additional ideas for search terms, if it
> doesn't give me exactly what I'm looking for. But what do you mean when
> you say "systematically".
I index with a particular goal in mind, which is to close the distance
between the reader and the information in the document. I want the index
to be an entry point to any information in the document.
My methodology is to work the document over like a masseur works over a
body, using strong, nimble fingers to trace and edify each keyword I
identify through reading. I work out the kinks and tension in the
structure of the information. I smooth it. I knead it. I get it sorted out.
> Did you invent a new version of the wheel
<blink> I dunno, what do you think?
, or did you use somebody's
> existing system for creating/populating indexes (like, out of a book
> [that you could name].
A lot of what I do comes from the indexing tools required by erstwhile
employers. For instance, I always liked the way some tools were designed
to suck out all of the index entries in a document, and put them in a
spreadsheet where I could then sort and structure them, and then put
them back into the doc. That is a mental model I use for indexing even
when the tool isn't available.
or from a website [even somewhere in a dark corner
> of Techwr-l])?
Likely. Maybe we can enlist a techwr-l spelunker to give us a guided
tour of such resources.
>
> Or have you given up on making indexes and just rely on the search
> facility of your Help or PDF, or maybe a FTS engine that you provide on
> the documentation CD??? Inquiring minds... :-)
Damn me but I love inquiring minds:-) at least as much as I deplore the
defiant incuriousity of a thrown-together index.
I started providing WinHelp files with FTS before FTS was officially
part of Help files. It took a little hacking, but was a great relief to
me, because try as I did, it was stressful trying to index very complex
technical documents, and I was thankful for a tool that gave users a
second chance at finding what they were looking for, even if I let them
down with the index.
>
>>> To me, the index is part of the linear form of
>>> documentation...a holdover from the print days.
>> Exactly. FTS took the user's ability to look things up to a new
> level.
>
> That's true, as far as it goes, but an index can sometimes provide terms
> that you hadn't thought of. "Oh, _that_ might be how they say what I'm
> looking for..."
I agree in theory and memory--I have seen masterful indexes in books,
and I am an admirer of entire books designed as indexes to fields of
research and information. But my earlier comment about the 'new level'
that FTS brought us to was in the context of tech writing for pay, where
we make inevitable trades offs of quality for delivery schedules. If we
can't have the time to work on the indexes, then FTS is a pretty darned
good (PDG) substitute. The business about problems getting results
where vocabulary is unaligned isn't really the indexer's problem, but of
course a very knowledgeable indexer (or author) who can account for the
variability of terminology in a field is an asset. Ditto for the user!
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
