B. Developing a Publications Department
Producing documentation for on-line presentation involves different concerns than printed paper documentation. This section briefly discusses some issues you need to take into account, but it is by no means comprehensive. See Appendix A, "Recommended Reading," for books that deal with this subject in depth.
Many companies are turning to on-line presentation of their documentation so that customers have easier access to their documentation, to save on printing and production costs, and to provide searchable linked information. If your company is considering such a move, be sure to research presentation and usability issues thoroughly.
Many issues arise when moving from print to on-line documentation. They involve writing, content, and management concerns.
Writing Issues
Because printed text has existed for hundreds of years, writers and readers instinctively know how to use it. On-line text, however, is new and constantly changing. People writing and using on-line text don't have the combined knowledge that comes from generations of experimentation and example. Guidelines for on-line documents are often incomplete, contradictory, or outdated.
- Writing style - To design on-line information, writers must change from the familiar writing style used for printed text to an unfamiliar, sometimes undefined style used for on-line presentation. Writers also often have a hard time going back and forth between the two writing styles.
- Scheduling - Time must be built into the schedule to allow writers and editors to develop their on-line writing style, and to transition between the printed and on-line formats.
- Platform-specific versions - Although some information providers use a "write-once publish-twice" scheme that presents the same documentation on line and in print, to most effectively take advantage of the benefits of on-line publishing, text should be written specifically for that medium.
Content Issues
- Access - You need to determine how the user will find and retrieve information, and what navigation aids you will provide.
- Text format - First, you must decide whether to duplicate information in both formats, or whether you will provide some information only on line and some only in print. If you choose the latter strategy, you need to decide the appropriate format for each type of information.
One typical strategy is to provide task or brief explanatory information on line, and more in-depth or background information in print.
- Graphics - If you decide to provide graphics in your on-line documentation, you must decide what format they will be in, how they will be included, and whether they will be linked.
- Hyperlinks - Some decisions to be made about hyperlinks include which information should be linked, and whether links should be accessed only through text or also through graphics. You may also decide to limit the number of links you want in a given body of information.
- Page design - Type size, page size, and page layout work differently on line than in print. You must decide whether to optimize your design for on-line or print presentation, or to use two separate designs.
Management Issues
- Scheduling - Designing and planning on-line documentation is usually more time-consuming than print presentation due to the possibility of linked information and to the ramifications of on-line display.
- Authoring tools - On-line documentation usually requires a different set of authoring tools than your standard word processing or desktop publishing software. These tools sometimes involve separate products for authoring and for on-line viewing.
- Outside resources - Support from other departments is usually required to a greater extent for on-line documentation than for print documentation. For example, you need to work more closely with graphics designers, product test, and the software integration team. When planning your on-line documentation strategy, make sure that the various organizations have agreed to provide these resources.
- Delivery mechanism - Will your on-line documentation be part of the interface (as is usually the case with on-line help, for example) or the product code? Your deadlines and testing procedures will be affected by this decision.
- Integration - How will your documentation be connected to the product? You need to find out how the user will access the on-line information, and how it will be installed and set up.
- Testing - Testing on-line documentation involves both the content of the documentation and the delivery media. Hyperlinks that the user can click to go rapidly to cross-referenced information, for example, are one of the benefits of many on-line delivery products. Each hyperlink must be tested to make sure that it goes to the appropriate location. If the documentation is being delivered as part of the product, it must work correctly with the product code. Finally, the medium itself must be tested to make sure that it works on all supported platforms.
- Legal - Presenting information on line usually means a change in how copyright and trademark issues are handled. Consult with counsel.
- Production - If your on-line documentation will be produced on CD-ROM media, you must determine whether it will be included with the product software or on a separate disc. This can also affect your packaging.
- ASCII text - Often, last-minute product changes or additions are documented in a brief on-line file in ASCII text. Consider drafting some formats for this type of presentation.
(Continued...)