October 1998
Future Docs, Part II
Putting It on the Line
cyberdocs
ILLUSTRATION: DAVE CUTLER

by PAUL D. LEHRMAN

Two months ago, I started a discussion here on the future of documentation, and how the folks who write user and technical manuals for audio tools may--or may not--be able to take advantage of the various "new media" bandwagons that everyone else is riding. This month, that discussion continues, and I hope it gets you readers--engineers, musicians, studio owners and manufacturers--thinking about this issue and starting your own discussions.

For those of us who live comfortably in the digital world, at this particular moment in the evolution of media, there are three principal ways to deliver content: paper, CD-ROM and the Internet. Paper has the advantage of being a completely portable medium, and it requires no special equipment to decode. Plus, we all have spent years developing the skills necessary to extract the information it carries. Paper's disadvantages are that it is expensive to make, it's expensive to ship and to store, and it's expensive to the environment, in terms of the number of trees that must be killed and the quantity of by-products that are spewed out during the manufacturing process (ever been downwind of a paper mill? I rest my case).

CD-ROMs are small and, from a cost-per-unit standpoint, inexpensive. Also, if they are designed properly, documents on CD-ROM offer indexing and hyperlinking that are way faster than even the best Evelyn Wood-graduate reader can get out of a book. The disadvantage is that a CD-ROM requires a dedicated machine to read, and for now, until we arrive at a palmtop standard, that machine has to be a full-fledged computer.

The advantage of putting documentation on the Internet is that once the editorial process is finished, it costs absolutely nothing to duplicate and ship, and it takes up no physical space. So it's a no-brainer, right? Not right.

It would seem to be a documentation or technical support manager's dream come true, to have documents available online, accessible to all, any time of the day or night. The same advantages that CD-ROMs have--instant access to any part of the document through hyperlinks and "hot" indexes and tables of contents--can apply to the Web. In addition, the information can be modified at any time with no need to alter any physical object, so that updates, corrections or other changes can be made without the need for another physical production run, either in pulp or polycarbonate.

But the catch, of course, is not only must you have your computer on while accessing these documents, you have to have it online. Some day we may get really practical, small, dedicated "network computers" (and a lot of folks are saying this genre was doomed before it was even born), but for the foreseeable future we've got to use a regular old computer for this. For many people, that means the same computer they've got running their studio.

Unfortunately for these people, a lot of current platforms have trouble accessing a modem and a MIDI cable at the same time, to say nothing of dealing with audio. I don't know if you've ever tried to pull down a large file from the Web at the same time you're recording a new track on your hard disk, but the experience isn't pretty. Even with a cable modem or T1 line, the World Wide Wait is not a pleasant way to get information quickly. The idea that you have to shut everything else down and twiddle your thumbs while you wait for a download that, when it's all over, might not even contain the information you're seeking, is horrifying, especially to those of us who work against tight deadlines--which means all of us. Waiting for a download to finish before you can go on with a session is about as productive (and as impressive to the client) as calling a break while you run to the other side of town because you forgot to buy enough tape.

If user manuals are going to be on the Web, and if we are to have any hope of accessing them efficiently, they are going to have to be organized very differently. Creators of the documentation are going to have to recognize that the Web is not just a giant amorphous repository of information. It has a dynamic and a set of priorities all its own. While CD-ROM drives have gotten fast enough that loading large graphic files doesn't cause everything else to come to a screeching halt, most people, especially those with ordinary dial-up connections, are a long way from being able to do that with the Web.

Moving user manuals onto the Web isn't just a question of converting Pagemaker or Word files to HTML. It requires rethinking the balance between text, graphics and other media, and organizing the information so that the most important stuff gets to the viewer as quickly as possible. It means breaking up the different bits of information into smaller bits, so that time isn't wasted accessing irrelevant or unnecessary data--you don't want to have to wait for a 250K graphic of the back panel to download before you can figure out the rating of the fuse that just blew.

Some companies are dealing with this problem by uploading their documents as PDF files. The PDF format, otherwise known as Acrobat, was created by Adobe and allows documents to be read with a piece of cross-platform freeware called Acrobat Reader. PDF documents can contain graphics and hyperlinks, as well as "hot" indexes and tables of contents, in which clicking on a topic takes you to the page cited, and they are even searchable. But PDF files can't be browsed online like HTML pages; you can't type in a word and have Excite or Lycos find it within a PDF document and then point you to the page. Instead, you have to download the whole PDF file first and then search it. Which means you have to be thinking ahead of time, so that the file is already on your hard disk (or a removable) before you need it. In an emergency, with the clock ticking, PDF documents that haven't been downloaded yet aren't much use. (Of course, you can always download it ahead of time and burn it onto a CD-ROM...Wait, isn't this where we came in?)

Since users expect it will take some time to download PDF files, they don't have to be as slim as HTML pages, but those designed for downloading need to be quite a bit leaner than those designated for fixed media. It's not uncommon for a PDF file on a CD-ROM, rich with high-resolution graphics, to take up 100 megabytes or more. Downloading this with a 33.6k modem would take a couple of days or more. It might make sense in some cases to break up a PDF file into smaller chunks, or even individual pages, to make each download faster, but that takes away some of PDF's advantage: If you don't know which page the information you're looking for is on, you don't know which section to download. If the index is a separate file, at least you can start there, and then, hopefully, save time by downloading only the sections that the index indicates you really need.

Potential pitfalls aside, there are some great benefits to having user manuals available online, beyond cost and efficiency. One of the strongest advantages is that you can include with the manual a sitewide search engine--in fact, this should be considered obligatory. You know that TV commercial for the removable-storage maker in which these two guys are desperately trying to find this tiny church in the middle of nowhere in Scotland so one of them can get married, and when they ask directions they get the whole history of the parish but no one will tell them where the church is? It's a wonderful ad (especially if you've ever had a conversation with a Scotsman), but it neglects an important point: It's not the medium that prevents us from finding the information we need, it's the way the medium is organized. The most versatile storage medium in the universe, and the fastest connection to it, are no damn good if you can't find the one piece of information you want.

There are a lot of commercial search engines now available that can be used by just about anybody with a Web site, for a reasonable fee and sometimes even for free, so there's no excuse for a manufacturer to have online documentation and no search engine. Setting up the front end of the engine so that it's easy to understand is crucial; arcane rules about quotations and commas and Boolean functions are not a good idea if manufacturers want to stay friendly with their customers. Smart parsing of phrases like "slaving sample rate" or "stereo links" or "@#$%&* error message" that display to users all of the instances of the words, in order of how closely they match the phrase, will save lots of time and aggravation, and it's a function that is easy to implement.

A bonus feature of online documentation for manufacturers is that they can gather the names of the folks visiting, by asking users to register or fill out a survey. The point of this is not so they can then sell mailing lists to porn providers or get-rich-quick schemes (and please don't get any ideas...), or even to bombard innocent visitors with daily marketing messages--that's a great way to get people pissed off. The point is to create an accurate database of people who need to be informed of changes in the products they use. If there's a software update, a newly discovered bug that needs to be avoided or a feature that wasn't explained well the first time around, users deserve to be told, and sending out e-mail messages informing recipients of the changes--with appropriate URL addresses and links so they can get more information from the Web site--is a fast and inexpensive way to get the word out. How about using the database for the occasional sales pitch or new product announcement? Sure, that's fine--if it's done with respect for the users' time and mailbox space. After all, somebody has to pay for all this.

Putting manuals online also gives manufacturers a golden opportunity to build a sense of community among their customers. I'm not necessarily talking about full-fledged conferencing and chat rooms; those can be nice, but they do take a lot of time and energy. (Ask the man who runs one!) But there are simpler ways to make users feel that they are in this together. One of the best is to set up Q&A or FAQ ("frequently asked questions") areas in which people write in their problems and questions, and someone knowledgeable within the company responds and posts the response for all to see.

What's great about doing this online (as opposed to doing it in a magazine column) is that the FAQ list can be expanded infinitely, so that all questions, past and present, can be available, and a search engine can let users quickly find any FAQs that apply to their situation. The same search engine used for the manual can be used for the FAQ list. For example, the search for "slaving sample rate" can not only point to the various places in the manual where this is discussed, and the place on the site where users can download the software revision that fixes the bug that crashes the machine whenever you select "pull-down"; it can also show all the questions that anyone has asked about the subject. After a certain critical mass is reached, more people will find their questions already answered online than will need to ask new questions.

An interesting phenomenon happens when user manuals, FAQs, software updates and the like go online: The tasks of creating documentation and of technical support start to merge. Tech support people, with their charts and diagrams, find they need to work closely with the people writing the online documents, in order for the information to be correctly integrated and up to date. If it's done right, and the communication flow between departments is good, then each group complements the other, and the site shows the visitor a unified presence. If there are territorial wars being fought between offices, with one team reluctant to take on user queries for fear of stepping on the other's toes, the site will reflect this, and users will get turned off.

One other thing that can help a company's documentation Web site gain acceptance and loyalty is a real man--or woman--behind the curtain. Adam Engst, a longtime commentator on the computer scene and publisher of the online newsletter "TidBits" (www.tidbits.com), wrote a fine article earlier this year about documentation, in which he opined that "All writing should have a voice. Show some attitude and let a personality come through in documentation." The same is true for a Web site. If there's a "real" person back there, it makes the experience friendlier, more engaging and actually much more valuable, because the user thinks that someone cares.

A lot of people who describe the Internet cite Gertrude Stein's quote about Oakland (or was it Cleveland?): "There's no there there." While that's intrinsically true in an abstract sense, a more serious, and avoidable, problem of many Internet sites is that there's no who there. A lot of Internet sites are like an old house that's been turned into a museum: lots of rooms and doors and secret staircases, and plenty of things to look at, but nobody home, nobody to talk to. The whole place is on automatic pilot; documents get uploaded and are just left lying around. But having a human being back there--even if it's a bunch of different people all pretending to be the same person--answering questions, signing welcome messages and just providing a sense of human presence, makes us feel much more comfortable and makes us want to keep reading and exploring.

This need for a coherent identity also means that "groupware"--tools that let many people work simultaneously on a document--has to be used with great caution in creating user manuals. The tendency for writers working in that kind of environment is to place all the emphasis on making the documents easily upgradeable, avoiding mistakes and staying out of each other's way. It often makes for a formula-ized document that is no fun at all to read, and will defeat its own purpose by turning off the reader.

Finally, aside from all the discussion about media, bandwidth, delivery systems and ancillary advantages, there is still one crucial issue that needs to be addressed: No matter how they are distributed, user manuals and documentation have to be written and organized properly.

An example: I recently was working on a project (a user manual, as it happens, so this becomes a "meta-example"), and I was using a program I was not very familiar with. I wanted to find out how I could create a multipage table with a header that was repeated on each page. The program isn't bad, but it's unbelievably counter-intuitive, a fact its creators have more or less acknowledged by shipping it with a huge online help file and a five-pound manual. So I looked up "tables" in the various indices and found 60 sub-listings, including dozens of pages on rulings, shadings, cell sizes, styles and how to paint my headers gray. But I saw nothing on how to create a header. I looked under "rows," "columns," "page breaks"--nothing. I looked under "headers"--and I found "heading rows, table." Glory! I went to that page and found this sentence: "You can even add heading or footer rows." That was all it said.

Fortunately, as I poked around the program, I discovered an obscure drop-down sub-menu that included the item "add heading," and so I got my headers. If I were ever forced--and it would have to be at gunpoint--to use this program again, I don't really know whether I would be able to find that menu again.

If a manual is written and organized and indexed badly, no amount of snazzy dressing and new media will help it. If it can't be used, then the product it's describing can't be used to its fullest capabilities, and that's a waste of our money and time, and of the manufacturer's money and talent.

Yes, do explore and exploit the new formats. Do take advantage of everything that is now ours: CD-ROMs, Web sites, DVDs and the more amazing media that are to come. But let's not forget the people who have to use what you come up with. If you don't keep focused on the user as the most important criterion for how to approach the new media, then there isn't much point in doing any of this.


Insider Audio columnist Paul Lehrman has written manuals for Roland, Kurzweil, AKG, UREI, Passport Designs and a few others he can't remember. He's still trying to get it right.

These materials copyright ©1998, 2001 by Paul D. Lehrman and Intertec Publishing