|
|
|
|
|
Many in the technical writing profession have deep-seated views about writing information for the delivery medium. They say that information designed for print is fundamentally different from information designed for online use. Admittedly, a printed manual may not be ideal for online usage.
If you have to weigh imperfectly publishing something versus not publishing it at all electronically solely because the text was originally written for print, the deciding factor should be how well your course of action serves your audience.
Withholding information does not serve your audience.
Calls to the Help Desk with questions that an unpublished document could answer do not serve your organization.
Remember that documentation, like software, can be improved from release to release. Over time, we can write or re-write our documentation in such a manner where it will adequately meet the needs of our readers regardless of the medium used to retrieve it.
Or stated another way, any efforts to streamline the text for quick and effective reading online will also benefit a printed version.
And even if we lack the time to neutralize our text to make it acceptable for all media, lets be realistic about our readers. Our readers are intelligent and have good filters. Advertising in newspapers, magazines, television, and the Internet has trained us well.
This means that technical writers can stop worrying about whether traditional terms like book/manual, chapter, section, and page number should be purged from the (online) documentation.
1 Our readers are going to read passed those terms anyway to get to the content that is of interest.
2 We shouldnt underestimate the historical significance of those terms and their usefulness in chunking the material and orienting readers.
3 When an online documentation system duplicates (my recommendation) or overlaps (a reader annoyance) with print/PDF, keeping the text identical even down to references to page numbers is a service to the readers. It provides the assurance that the online documentation or PDF documentation is complete and permits using the two in tandem.
4 If the hyperlink works and does indeed take the reader to that information, the big taboo of a page number in an online medium isnt going to be a hindrance to usability.
» Jared Spool of User Interface Engineering states that hyperlinks should give the reader a scent for the information and where they will land.
» If our cross-reference text says Turn to page 60 for more information about Topic X, our readers won't care that there is not a page 60 in HTML as long as the hyperlink works and gets them to the equivalent of page 60 and Topic X.
» The wording and numbering of cross-references for book (The Installation Book), chapters (Chapter 5 Configuration) and figures (Figure 4.12 Schematic of X) can and do have a place in print and online help -- much to the chagrin of online help purists.
» If you must be a purist, become intimately familiar with FrameMakers conditional text.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02