How to make a gigantic doc set easily searchable?

Subject: How to make a gigantic doc set easily searchable?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Samantha Slate <samantha -dot- slate -at- gmail -dot- com>
Date: Sat, 23 Sep 2006 08:53:44 -0400

Samantha Slate wondered: <<Much of our documentation is intended to help in-house consultants and tech support, as well as the occasional tech-savvy customer, with the very complicated task of installing and configuring our products. Currently, we publish all of our docs as PDFs.>>

PDFs designed for onscreen use, or PDFs designed for printing that your audience is forced to use onscreen? I say this not to be snide, but rather to reinforce the difference. It's important and underappreciated.

<<However, we've been getting complaints recently that the doc set is not easy to navigate. We are looking at reorganizing the books in ways that will seem more intuitive to users, but even so, we would like to be able to offer some sort of advanced-search capabilities that lets the user search more than one book at a time, using more than one search term (unlike PDF, which only lets you search for one text string at a time).>>

Make sure you understand specifically what they are saying is difficult. I've seen many people rush off all full of energy to solve the wrong problem. In terms of the search engine, I'm not sure I can help you (not even remotely a PDF expert), but my take on this is that if readers need to use the search function, then your table of contents and index are failures.

Admittedly, this is an exaggerated statement, but I've made the statement that extreme specifically to make a point: search tools must complement, not replace, effective navigation.

<<The obvious thing (to me) that comes to mind is a password- protected web site.>>

Given that your main audience is in-house staff, password protection isn't at all useful. Even for your customers, why would you bother protecting information that they have freely available in PDF? Worst- case scenario is that if someone wants to steal the information, they'll run it through OCR software--in fact, there's at least one program designed specifically to extract text from PDFs into (say) Word, and if a client has Adobe's Creative Suite, they can directly import PDFs.

"Information wants to be free; writers want to be paid." (I believe Bruce Sterling or possibly Cory Doctorow originally coined the phrase.) The important thing here is that your documentation is useless to anyone who doesn't already own your software. So who cares if someone steals it? Free up the information, and make them buy the product. (Think of this as public-key cryptography for documentation: you need both keys to do anything useful. <g>)

<<But is it possible to single-source our documentation so that it can be used both as the content of such a Web site *and* in a PDF- publishable format, since some customers do still want the PDFs?>>

It's easy enough if you plan to do so right from the start. This can be as simple as adopting a continuous, one-column design. For example, newspaper-style layouts in which stories break and interweave across multiple pages can be very difficult to "unroll" into a series of Web pages, whereas a linear text flow with each level-1 heading denoting a new page (in print or on the screen) is relatively easy to turn into HTML. The process can also be more complicated, involving SGML/XML and single-sourcing, which lets you produce complex print layouts that turn into simple and elegant Web pages.

The details of SGML/XML single-sourcing lie well outside my area of expertise, but there are experts here you can ask. Write back to techwr-l with specific details of your software and you'll get some more specific advice.

<<Also, have any of you ever been asked to enhance search capabilities for your documentation? If so, how did you respond to the request?>>

Since I spent a significant amount of time creating kick-ass tables of contents and indexes, the question never arose. <g> But we have several PDF experts here who can help.

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

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:
how to make a gigantic doc set easily searchable?: From: Samantha Slate

Previous by Author: Acrobat 8?
Next by Author: STC Seminars?
Previous by Thread: 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