Advice for Single-Sourcing

by Hedley Finger

I have seen the future and it works. We have just finished our first single-sourcing project using mif2go to convert FrameMaker source files to HTML Help *.chm files. These files are also the source of our printed user guide AND a hyperlinked PDF of the user guide placed on the distribution CD.

There was considerable once-off pain setting up conversion templates (including CSS files) and conversion options but our next project will be much faster. The converted files DO NOT require ANY hand tweaking -- we just hand over to the release people to put the *.chm file on the installer CD.

Our testing and support people are rapt, and consider the new help far better than the old help. An outsider would have no inkling that the help was produced in this way.

WHAT IS THE RATIONALE?

Be clear WHY you want to single-source.

Reduce double-handling and maintenance.

In our case, we were developing content twice, once in the printed book and again for the help, using different tools for each.
Manage closely related products for different markets.

Many of our products are compiled from a single codebase for:
1. different markets,
2. different target users,
3. different platforms (Mac and Win), and
4. different versions, e.g. "Lite" and "Pro".
FrameMaker's conditional text, book, and variables features enable us to have a single "docobase" by analogy and reliably generate a deliverables set for each product.
Present information in different media.

Currently we produce a PDF to go to the printer, another fully hyperlinked PDF exploiting coloured links (xrefs, ToC, index page numbers) which is included on the distribution CD, and HTML Help (soon to be cross-platform help), and, in the future, Web based help.

RULES FOR SUCCESS

Single-sourcing can work if you follow these rules:

Start with your destination. Design the help structure and navigation requirements first, then work back to design the FrameMaker templates.

Plan, prototype, revise, rework.

In particular, pay attention to how FrameMaker elements will map to help elements (HTML tags, Heading 1 formats, or whatever).

Your documents do not have to be painfully simple -- they can be as complex as you like, just VERY consistent.
Design a strict hierarchical structure for your documentation.

We also have a strict folder tree structure and naming conventions for files and formats to facilitate batch processing via scripts, and so scripts, etc. can locate files by relative paths.

This allows us to ramp up a new project quickly and gives the writers and artists a uniform environment in which to work.
Shoot writers who depart from the template formats, document structure, folder tree, and naming conventions. The rest will get the message soon enough ... :o)
Use the ability of most conversion tools to temporarily apply an FM template to the source files to customize the output.
Use condition tags to selectively hide press-only and help-only material. For example, the book contains many screen shots. Since the users will have the application open when consulting the help, the actual window will be open. You can hide many screen dumps with a press-only condition.

Your procedures will also have many confidence reinforcers or confirmatory text. For example, in "1 Choose File > Open. The Open File dialogue appears.", you can suppress "The Open File dialogue appears" sentence in the help.
Make sure you plan suitable entry-point topics. Otherwise, you may find that you have four equally eligible targets after pressing the F1 key in the Gizmo Details window.
Make sure you have mini-ToCs under each overview topic pointing to the headings next lower in the hierarchy. Include bulleted lists of cross-references to related topics at the ends of topics lowest in the hierarchy. You don't need those [Related Topics] buttons; a bulleted list of xrefs will do.

(Although most conversion tools have means to insert triggers in the source files to cause special HTML with JavaScript macros to be included where required in the output stream. These can handle [Related Topics] buttons and fancy stuff.)
Use lots of in-line cross-references and lists of cross-references as "advance organizers" (as advocated by Information Mapping).

Draw a dependencies graph (i.e. before you can do C you must first do A, for example, Preferences or Options that must be specified before you can do some other task). Then include back xrefs and forward xrefs to the parent and child topics in the dependency graph.
Develop a strict workflow with checklists at each milestone. Pay particular attention to production, the point at which you generate all those different deliverables. So easy to get lost in condition tag heaven (NOT). 8^)

But if you think you can take some legacy manual and magically transform it into help or Web pages, or anything else, everything the sceptics in this thread have said will come true.