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.
How to make a gigantic doc set easily searchable? (take II)
Subject:How to make a gigantic doc set easily searchable? (take II) From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Matt Horn <mhorn -at- adobe -dot- com> Date:Tue, 26 Sep 2006 09:15:28 -0400
Matt Horn notes: <<It's a pretty tall order for even a great set of
TOCs or indexes to help navigate a "gigantic" doc set. Do you really
expect your users to check multiple different tables of contents or
indexes to find info?>>
Note that "tall order" means _difficult_, not impossible. Many years
ago, I used Interleaf TPS, and we're talking five or six thick books
of documentation... including a master index for all the books. I
_lived_ in the index, and almost never had trouble finding what I
wanted to find. And once I understood the overall purpose of each
book, I was often able to save time by going to the book-specific
index or TOC.
So don't give up on the idea of diligent indexing and careful
creation of TOCs just because it's difficult. That's why we're paid
decent salaries: to make the difficult (organizing and creating
information) seem easy when judged based on the ease of the results.
Don't forget: search engines are useless if you don't know what
you're looking for, but a TOC will give you an idea of keywords to
look for in the index, and good use of synonyms in the index will
help you find the actual terms you're looking for.
<<The product I work on right now has 6 books (well, 5 books and a
huge online reference) in the doc set. I wouldn't want to subject
users to that.>>
Following the Interleaf example, you won't be "subjecting" readers to
anything if you've designed the doc set well. Symptoms of poor design
include forcing readers to have two books open simultaneously to
solve a single problem*, forcing readers to repeatedly consult five
books worth of indexes to find a topic, and making it unnecessarily
difficult for readers to know which book to look in. And for really
large doc sets, single-sourcing shines: write it once, and publish it
in every book that it's relevant to so readers rarely have to search
several books.
* That's bad design only if it's a recurrent or simple problem the
reader is trying to solve. Sometimes you really do need to consult
several books when the problem is complicated. That's life.
<<Maybe you could produce a cross-book index and/or TOC, but the
examples of those that I've seen were far from great.>>
That's because indexing is regarded as an expensive and optional
luxury, not an essential part of a large book. And as for the cross-
book TOC, it's a trivial exercise to create one even for the most
complicated documentation set. Worst-case scenario, you copy and
paste the individual TOCs from separate books. Best-case scenario,
you start with a clear blueprint that defines the contents of each
book clearly, then automatically generate the TOC using something
like the "book" function offered by most software. I've even seen
"meta" TOCs in which you have a "to solve class X of problems, look
in book X" information. Really valuable stuff!
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
