RE: [inframe] Single-sourcing = myth? (and other topics)

["Glenn Maxey" <glenn.maxey@xxxxxxxxxxxxxx>]

I read Jane A. Hemmi's article on "Differentiating Online Help from Printed Documentation" in the July/August Intercom issue. I agree with Bill Swallow when he wrote:

> The article is full of sweeping generalizations and misinformation.
> It mentions "myths", yet counters them with very weak evidence and,
> ironically, more information stemming from age-old misinformation."

I guess what annoys me the most is that she implies that online help cannot be linear as it is with a printed manual.

The main difference in an online help system from printed documentation is that the writers allow the application program to enter the documentation system at clearly defined entry points (e.g., content IDs). 

What is wrong with overlaying this on on top of a well organized, linear manual, which is what single-sourcing can do? Moreover, the very things that seem to make an online help system non-linear (cross-reference hyperlinks between topics, lists, indices, table of contents) have parallels in printed manuals. Thanks to tools, they tend to be consistently more accurate when new material is added or subtracted, and can be even more dynamic when the output is PDF/HTML.

Chunking of the material is important. However, even a linear manual chunks the material into books, chapters, sections, etc. A problem with online help systems in the past has been that they over-chunked the material. They chunked the material into such small pieces, they they lost context and became next to useless even in context-sensitive help, which was made even worse when writing of the topics was secondary to the mechanics of mapping application contents IDs to topics. "The Fritz button turns Fritz on and off." Duh! I can see that from the interface! What does Fritz do and why should I care?

User Interface Engineering [www.uie.com] studies have proven that users are not adverse to scrolling as previously thought, hence we don't have to overchunk our material (bite-size or pop-up hell) if it doesn't call for it. From experience, I know that print-chunks can serve the reader well in online help systems. Moreover, as a writer who wants to have control over the entry points taken by my readers (what they know and what they don't know), the chapter/section chunks from my linear structure serve very well as content ID locations for the application.

Let's give our readers some credit for having adequate fluff/detail filters to find what they need in a topic that is larger than two sentences.

My point is that truly useful online help systems should also have the ability for a reader to navigate them linearly front-to-back -- in addition to hyperlinks from the application, table of contents, index, and other sections. (Nothing bothered me more in Windows 95 era online help than secondary windows and pop-ups, because if they contained useful information, they still didn't guarantee that I could get there from browsing, the index, or the table of contens.)

Ms. Hemmi can wax philosophical about online help being fundamentally different from printed documentation, but it will ignore the realities of being a technical writer in today's world. Technical Writers are charged with writing documentation for a product; and, oh yes, management would like that printed for the customer's bookshelves, in PDF to send to sales prospects, HTML for website customer support, and online help tied to the application. Is next week too soon? And don't forget that this is version 1.0; you'll need to update the content and produce the same output formats again and again for every release of the product.

If the writer knows this from the onset, it won't take much to curb or conditionalize their print/online specific language, employ standard tools (e.g., FrameMaker and Mif2Go/WebWorks Publisher), and then single-source it. The tools can be tweak to produce chunking and layout appropriate to the medium even down to the wording used in cross-references/hyperlinks. Repeatability and maintenance are the buzzwords. 

When Ms. Hemmi talks about "unique criteria for the medium," I say the true criteria is that content is always king, and there is no substitute for well organized content. A well-organized printed manual can be single-sourced to online and will remain well-organized. Its linear structure is a time-tested organization technique that lends itself well to having an additional, non-linear, hyperlink structure overlaid upon it. Not only does it help resource-strapped, time-strapped technical writing departments, but lo and behold the readers like it because its logical structure helps them find the needed information.

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn.maxey@voyanttech.com

** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **