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 leximation.com> 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. > www.leximation.com > +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 gmail.com > > > > -- Carrie Baker carriebak at gmail.com
