Structured FrameMaker and XML: Document Development on a Small Budget

At the general meeting on December 6, Fei Min Lorente gave a presentation about a subject that many writers still find daunting; she spoke of converting to Structured FrameMaker and using XML to single-source information. To my mind, either of these topics would be food for thought, but Fei Min went even further. She described how to do this as a single writer on a small budget.

In terms of background, Fei Min told us that she worked for Dspfactory as the lone writer until AMI Semiconductor, a company that mostly manufactures and sells chips, bought Dspfactory in November 2004.

The Obstacles

Fei Min was now faced with entirely new challenges; she had multiple products, SMEs, and reviewers. For example, she now had to deal with the following groups, each with their own areas of interest and possible issues:

Group	Areas of Interest / Possible Issues
The Medical and Wireless Products Business Unit	This unit designs chips that are programmable for hearing aids and headset manufacturers.
The Software Tools Group	This group develops software for programming, testing and evaluating.
SMEs	Some SMEs want to use WYSIWYG editing and some want to write in XML.
Reviewers	Reviewers are located all over Europe and North America, although most are comfortable with online reviewing.
Customers	Customers want both searchable online and print versions of all documentation.

In the end, Fei Min realized:

She was wasting time converting Word documents to FrameMaker.
She needed to accommodate XML.
She needed to single-source code as well as documentation.

My first thought was that this was a large task for a documentation team; but, there was no team. There was just Fei Min with the following resources:

one technical writer
a 30-hour work week
three months to research alternatives
six months to produce a new set of documentation
a budget that is less than $10,000 (Canadian)

The Possibilities

Fei Min researched solutions and she presented us with a list of the alternatives that could get the job done.

Author in Authentic and publish in FrameMaker or publish directly from XML.
Author in Word and publish in FrameMaker.
Author in Structured FrameMaker (with multiple tools to assist).

The Solution

The winner was … #3! This proposal included the following tools:

FrameMaker: familiar, great publisher, supports XML
FinalDraft: online reviews, tracks discussions, links to FEI MIN
Mif2Go: robust HTML conversion, including figures and equations; cheaper than WebWorks
Python: object-oriented scripting language, good at text handling, and free!
Adobe Acrobat: doesn’t everyone use this?

After Fei Min presented us with the chosen solution, she was careful to offer the following caveats:

No tool is perfect.
You must invest time if you’re not investing money.

On the other hand::

Taking the time to learn keeps the knowledge in-house.
Using XML does not have to be expensive.
You can produce documentation while converting to XML.

Fei Min also noted that even with the limited resources available to her at the time, it was possible to set up structured FrameMaker for one document in a month; mind you, that was working at it fulltime. There are better resources available now—for more information, check out the Adobe website.

The Savings

In the end, the final cost of the project, including two copies of FrameMaker, was $3,506.24.

Fei Min gave us an overview of the results and benefits of the project. Time was saved because there was no manual document conversion—between 2003-2004, she spent an average of one hour for every eight pages converting Word to FrameMaker—and time was saved because reviews were done online. This also saved many trees, which is of course a good thing. Insofar as stakeholder satisfaction was concerned, the authors that used XML were happy, while the Word users had some difficulty switching to FrameMaker. Fei Min also included herself as a stakeholder, and she was very happy, because the Structured FrameMaker reduced the amount of time she spent having to reformat.

In the end, what I took away from Fei Min’s presentation was that converting to Structured FrameMaker and making use of XML was not only possible for any size of team and budget, but that it was not nearly as scary as it was made out to be. Now, I only have to convince the powers that be in my place of employment that this is so.

The chapter would like to thank Peer Group and Campana Systems Inc. for donating the door prizes for December. Congratulations to our lucky door prize winners, Gina Jackson and Mike Levey!

About Donald Johnstone

Donald is our chapter’s Program Manager, and he’s travelled all over the world (even Africa!) to book the talent for the monthly STC meetings. He would like to do some more travelling, but our limited budget, and supporting his teenage son, currently prevents him from touring.

Donald’s background in programming and system analysis have provided him with a solid foundation in his career as technical writer…so far. He loves science fiction, history, photography, and his wife—not necessarily in that order.

In this issue: