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!

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart ghart -at- videotron -dot- ca

(try geoffhart -at- mac -dot- com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
RE: how to make a gigantic doc set easily searchable?: From: Matt Horn

Previous by Author: STC Seminars?
Next by Author: Pop-up Window vs. Dialog Box?
Previous by Thread: RE: how to make a gigantic doc set easily searchable?
Next by Thread: Re: how to make a gigantic doc set easily searchable?


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


Sponsored Ads