Slashdot Mirror

For starters, a properly designed manual (regardless of whether it's printed, in PDF or HTML or whatever) reduces the need for word-based searching. The theory being that the people writing the documentation break it up into "atomic" pieces, and give each piece a useful title. Then you have an index and glossary which cover all the "jargon" words for your product, along with all the useful or moderately useful terms.

In the event that you want to provide a search capability on your on-line documentation, there are self-contained tools available such as Verity's (closed-source, proprietary) Search 97 CD Web Publisher, which is a self-contained web server and search engine. There is Perlfect Search, which is not stand-alone, but could probably be incorporated into a self-contained documentation server.

Failing all else, you give the customer permission to copy the documentation to their own Intranet site, which will usually have some kind of indexing/searching system available.

IMHO, PDF is the worst thing to ever happen to the Internet/World Wide Web. Here is a format that:

• can't be re-rendered to fit the screen I'm using,
• requires a specific paper size when printing (ie: US documentation usually wants US letter, while British will usually want A4),
• dictates that certain fonts are used,
• looks ugly on screen, and only looks good on paper, because that's what the document was designed for, and
• wastes bandwidth (Internet or Intranet) because you have to download the whole thing to view one page.

One great advantage of XML/HTML documentation is that it can be read using Lynx (after being served up by your web server), or converted to doc format for Newton or Palm devices (or in fact, any format you want).