XSLT is a "scripting" language for processing XML files. See .. http://en.wikipedia.org/wiki/Xslt
XSLT is not a Frame-specific language, and if your developers use XML very much, someone is bound to be able to write a simple XSLT script to generate a list of parameters/fields .. something that might look very similar to a TOC that you would generate from Frame. With this you'd be able to do a visual compare between your FM TOC and the "TOC" generated from the XML file. ...scott Carrie Baker wrote: > 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 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 >> > >> >> > >
