Soltys Family Home | Internet Resources For Technical Communicators | Articles | Core Dump

The Joy of Single-sourcing

by Hedley Finger

I have seen the future and it works. At MYOB® (Mind Your Own Business) Australia, 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 the 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. It has a navigation pane with Contents, Index, Search, and Favorites tabs, a toolbar with Hide [navigation pane], Prev, Next, Back, Forward, Print, Options, and Welcome (custom Home) buttons. An outsider would have no inkling that the help was converted from FrameMaker source files as the appearance is completely different from the printed book and hyperlinked PDF. You, too, can single-source successfully provided you plan beforehand and your team understands the process.

What Is the Rationale?

Be clear why you want to single-source.

Reduce double-handling, maintenance, and information becoming out-of-synch in different documentation deliverables.
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: (a) different markets with different legal and accounting enviroments, (b) different target users, (c) different platforms (Mac and Win), and (d) different versions, for example, "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 (cross-references, 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.

The content in each deliverable is not exactly the same. Some is hidden using condition tags. There are extra files in the online help that explain how to get the most out of help, describe new product features, and include reference information dialogue by dialogue. These files are simply omitted when we do the printed book and hyperlinked PDF.

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, test, 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. A content developer can transfer from one project to another and immediately know where everything is.

Shoot writers who depart from the template formats, document structure, folder tree, and naming conventions. You only have to do this two or three times for the others to get the message ... :o)

Use the ability of most conversion tools to temporarily apply an FM template to the source files to customize the output. For example, the help template (temporarily) converts cross-references from the book format ('see "To create a new customer card" on page 98') to the help format ('see _To create a new customer card_').

Use condition tags to selectively hide press-only and help-only material.

For example, the book contains many screen shots. Since the actual window will be open when the users are consulting its help, you can hide many screen dumps with a press-only condition.

Your procedures will also have many confidence reinforcers or confirmations. For example, in "1 Choose File > Open. The Open File dialogue appears.", you can suppress the confirmation sentence "The Open File dialogue appears" 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.

We have set up entry point topics to give immediate quick-reference information to experienced users. When a user presses F1 in any dialogue, a topic containing a table of widget descriptions (that is, 'What's This' descriptions) appears. This is for experienced users. Below the table is a list of cross-references to related procedures and topics that novices can follow to complete relevant tasks.

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 cross-references 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 (that is, 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 cross-references and forward cross-references 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 single-sourcing sceptics say will come true.

Hedley Finger
Documentation process implementation
Adobe(R) Certified Expert, FrameMaker 5.5
Hand Holding Projects Pty Ltd
ABN 98 007 418 153
Technical consultancy for electronic publishing
28 Regent Street
Camberwell VIC 3124
Australia
Tel +61 3 9809 1229
Mobile +61 412 461 558
E-mail mailto:hfinger@handholding.com.au

Soltys Family Home | Internet Resources For Technical Communicators | Articles | Core Dump