Re: advice for single-sourcing ( Framemaker + Webworks)

[hedley_finger@xxxxxxxxxxx]

Andrew Plato and all ...

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:
     (a) different markets, (b) different target users, (c) different
     platforms (Mac and Win), and (d) 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.

Regards,
Hedley

--
Hedley Finger
Technical Communications/Technical communicator and FrameMaker mentor
MYOB Australia <http://www.myob.com.au/>
P.O. box 371   Blackburn VIC 3130   Australia
12 Wesley Court   Tally Ho Business Park   East Burwood VIC 3135
Australia
<mailto:hedley_finger@myob.com.au>
Tel. +61 3 9222 9992 x 7421
Mob. +61 412 461 558


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