Do I need to jump into the Structured FM pool?

[mcarr at allette.com.au]

Lin Surasky wrote:

> So I'm thinking that structured FM must be able to help, in that I could
> somehow create element tags for Fixes and Issues, and then just change
> the element tag for the Issues that have been fixed and somehow
> regenerate the documents (how, I don't know -- do I need to maintain
> this in a spreadsheet or database?) so that the content is moved to the
> correct section along with its cross-referenced bullet (each section has
> a bulleted list to make navigation easier). Oh yeah, and can they be
> re-sorted by section into numerical order?

Structure can certainly help - if you store your manuals in XML all the
manual work can be eliminated. Chances are your bug tracking system can
export reports in XML. An XSLT stylesheet can very easily replace the
existing version of this information so when next you open the document in
FrameMaker, the data is all updated.

Of course, this open up myriad possibilities for customisation of the bug
information - separation of code and interface bugs, ordering by severity
for developers and date for managers, whatever you can imagine.

The point is that generating this information is best accomplished by your
bug tracking software, not by FrameMaker. It can generate a report of open
bugs, so why would you want to do exactly that in FrameMaker? You may want
to dump it all into FrameMaker and conditionally display it - providing
different views for different audiences is very much part of what
FrameMaker should be responsible for.

Probably the biggest gain that you can get out of XML is the ability to
make your information span applications, but to do so you obviously need
to look wider than FrameMaker. You're doing software manuals by the sound
of it, so you presumably have access to programmers. If I was you, the
first step would be sit down with a couple of them and see if you have the
resources to develop a scalable, robust system. I recommend against the
"toe in the water" approach - I've seen too many people spending too much
time trying to gradually improve them into the system that they knew they
wanted but weren't brave enough to embark on in the first place.

Measure twice, cut once and have fun!


Marcus