Stimulus Online

The January meeting

Single source of contention

March/April 1999

by Christel Kurz

Christel Kurz is a senior STC member and experienced Help developer.

The panel discussion on Help was a raving success! Not only did we fill to capacity one of the largest rooms at the RA Centre, but we were thoroughly stimulated by the discussion. This became evident as war almost broke out when Lynda, in her concluding remarks, wanted to see a show of hands for the two sides (or was it three?) of the single source debate. The proceedings of the evening went roughly like this (for introductions to the panelists, see the Jan./Feb. issue of Stimulus).

Benefits of controlled English

Ralph Calistro gave three good reasons why he promotes controlled English in Help topics:

A Help topic is intended to promote immediate understanding.

A Help topic has limited space—don't waste that space with unnecessary words that add no value.

Windows Help and other online documentation reach a wide audience with a large percentage of readers being non-native English speakers.

Ralph defined controlled English as a language limited in forms and syntax. Some related techniques we can all practice include:

Using one word for only one meaning

Eliminating synonyms

Keeping sentences shorter than 20 words

Using the active voice

Eliminating noun strings

Media-neutral information modules

Mark Baker introduced the single-sourcing issue that often revolves around creating Help. For Mark and his colleagues, single-sourcing means writing media-neutral modules of information. Writers must learn to write without knowing how the information will be packaged. Mark convinced a good number of us that how we write is NOT affected by the media that the information is presented in. We must write clear, concise, and easy to understand modules of information regardless of the packaging. However, it is the media and the audience's purpose that determine how the information is packaged.

This type of single sourcing compares to object-oriented programming. Each module of information in the database must be "typed" and must have defined inputs and outputs. This translates into defining which information modules must precede this module and which must follow. It seemed we were all a little comforted when Mark agreed that certain types of information are more suitable for being "typed" (e.g., programmer's reference information). Mark and colleagues can produce WinHelp, Programmer's Reference Guides, Quick Reference cards, or a training course on the programming language all from the same pool of source modules of information. The trick is to separate content, synthesis, and presentation.

A solution for the impossible task

WandaJane Phillips told us a completely different single-sourcing story. A client wanted her to produce Help, a user's guide, an administrator's guide, and a training course from a single source. The client actually thought this was possible! WandaJane found a happy compromise. She decided to offer enough single-sourcing to please the client, but still produced separate deliverables for the varying audiences. She wrote all procedures into one

source of reusable modules. Each deliverable contained audience-specific information and applicable procedures taken from the repository of procedures. WandaJane shared the lessons she learned from this—specifically that planning is the most important item in every documentation project.

Push-button conversion

George DaNova took on a little project of his own for the sole purpose of reporting its outcome at this panel discussion. He wanted to prove that it was possible to achieve "push-button conversion" of FrameMaker documents to HTML Web pages. He recommends Quadralay's WebWorks Publisher as the tool of choice. George noted that it takes time and patience to learn how to get the output you want, and you should have prior knowledge of HTML. Unlike FrameMaker's built-in conversion tool, WebWorks Publisher

Gives you complete control over the conversion

Lets you map each FrameMaker style to an HTML tag

Converts native FrameMaker graphics into GIF or JPEG

Assuming you did enough up-front planning and your FrameMaker docs use styles consistently, you can reuse the conversion "template" you create in WebWorks Publisher and get the same HTML results each time, at the push of a button.

The Corel way

Nick Simons shared some of the history of why Corel chose the opposite approach to conversion. Let's just say that they were forced to reintroduce paper books by popular customer demand, and his department had the mandate to produce the books from existing Help, at no extra cost. In this case, the Help was to be the source and at the push of a button—out comes a book!

Corel had closely followed Microsoft standards for WinHelp, but some conventions were not suitable for books. Fixes had to be made to the source help files, for example:

Procedures regained their introductory statements.

The popular "click here to read more" links were changed into cross-references that worked both in book and Help.

The structure of the source RTF files was reorganized.

The last point caused the most work. No longer could one RTF file contain all definitions and another all procedures, and so on. The topics in the RTF files had to be written in book-like order.

Corel programmers were called upon to create a custom Help authoring tool that imposed this structure. I believe the conversion tool itself was built in-house too.

Was it a Help seminar?

The focus was almost entirely on single sourcing, but yes, it was a Help seminar—not about learning how to do Help, but about planning issues. How can we with our reduced cycles and budgets produce books and Help and even other media? Do we produce

The same information in different media?

Different information in different media?

Either of the above, from a single source of media-neutral information modules?

Thanks again to the panelists and the audience who participated in this interesting evening. Note that the February issue of Intercom has a feature article on single sourcing. Looks like we were ahead of the game!