As I hoped I am getting some interesting answers.
However, since I have not worked on structured Frame yet, and am not
so famailiar with the terminology, can you explain was an XSLT
transformation is?

On 5/21/07, Scott Prentice <sp at> wrote:
> Hi Carrie...
> For starters, you should get ahold of an XML diff tool (just google "xml
> diff", and you'll see lots of options) so you can determine exactly what
> has changed between versions of this XML file. You should be able to get
> one of your developers to write an XSLT transformation that would
> generate a list of the parameters in the file, and you can compare that
> list to a "TOC" list generated from your Frame file .. this will let you
> determine what's missing or extra.
> In an ideal world, you might consider authoring the "descriptions" of
> the parameters and fields in XML (in Frame or another XML editor), then
> run an XSLT transformation on the "descriptions" file and the file
> provided by development to generate the source for your final
> documentation. You'd just open the generated file in Frame (after
> setting up a structure application), and it would be ready to print. The
> EDD could be set up to render any missing descriptions with a big red
> "MISSING DESCRIPTION" note, in which case you'd add that to the
> descriptions file and regenerate.
> Obviously this would take some time and money to set up, but in the long
> run will probably save a lot. Just having the ability to easily diff the
> versions of the XML file will probably be a big improvement though.
> Good luck!
> ...scott
> Scott Prentice
> Leximation, Inc.
> +1.415.485.1892
> Carrie Baker wrote:
> > 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!"
> >
> >
> > Marcus
> > _____________________________________________________________
> > Carrie Baker
> > carriebak at
> >

Carrie Baker
carriebak at

Reply via email to