Slightly connected to this.
We have Frame 7.2, not structured and are doing fine.
We are a small (understaffed) department of 2 half time writers.
There is one very large chapter of a user guide which is based on
information from the programmers .xml file.
Their xml file consists of a list of parameters with various
explanations about them. This file is used by the application.
As writers we need to list all of these parameters and explain them.
Documentation began when the list was a very small list. The SME gave
us a word file which was eventually converted to Frame with the
information the users required.
Since then everything has grown a lot.
The xml file now contains a over 2000 parameters.
Various tech writers worked on it over the years and at some point a
lot of parameters were missed out.
For every product release a large number of parameters are added to the list.
The problem I am facing is how to identify the parameters that are
currently missing from the Frame file, and in the future how to
smoothly make sure the file is kept up to date. As new features are
developed R&D tell us which parameters are added, but if parameters
are changed or removed we do not really have a way of tracking.
R&D tried to give us an Excel file (i.e. they opened their xml file in
Excel and saved it for us....), but it actually messed up the
information, since there were also sub groups of parameters (e.g.
parameter x contains the following 50 fields, then each field appeared
as a stand alone parameter).

As is mentioned below, Frame knows how to talk to xml, so what I am
looking for is whether someone can tell me, how I can make my
alphabetical list in FrameMaker (which I am willing to turn into a
table or something else), talk directly to the xml list to see what is
missing from my list and in future easily identify what to add.
However, the entire content of the 2 lists are not identical, since
the Frame file (or user guide) has to give the user a full explanation
of the meaning of each parameter, which the .xml file does not do.

(or what can I ask R&D to do to help us, as each time they only give
us this messed up Excel file)

(Oh and my boss does not want to spend too much time on this!)

Marcus wrote

"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!"

Carrie Baker
carriebak at

Reply via email to