Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

Single-Sourcing Rant

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.

“Don’t let perfect be the enemy of the good.”

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.

Time Heals

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.

Give the Readers Credit

And even if we lack the time to “neutralize” our text to make it acceptable for all media, let’s 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.

Analog Not Anal

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 shouldn’t 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 isn’t 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 FrameMaker’s conditional text.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02