Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
See also: http://www.w3schools.com/xsl/default.asp Yves Barbion Documentation Architect Adobe-Certified FrameMaker Instructor Scripto bvba Asselsstraat 65 9031 Gent Belgium T: +32 494 12 01 89 F: +32 9 366 50 32 BTW (VAT) BE 0886.192.394 skype: yves.barbion Mike Feimster wrote: > Carrie > > XSLT is short for Extensible Stylesheet Language Transformations . It is > a programming language used to transform XML from one syntax to HTML, > plain text, or another XML syntax, etc. > > For example. Lets say you have an XML file that looks like this: > > > Hello World > Lorem Ipsum . . . > > > You can use XSLT to transform it to the following HTML: > > > ... > > Hello World > Lorem Ipsum . . . > > > > This is an XML technology, not a structured Frame technology, but you > can incorporate it with structured Frame. > > Mike > > -Original Message- > From: > framers-bounces+mike.feimster=acstechnologies.com at lists.frameusers.com > [mailto:framers-bounces+mike.feimster=acstechnologies.com at lists.frameuse > rs.com] On Behalf Of Carrie Baker > Sent: Monday, May 21, 2007 1:08 PM > To: Scott Prentice > Cc: framers at lists.frameusers.com > Subject: Re: Getting data from xml into Frame was,Do I need to jump into > the Structured FM pool? > > 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
Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
Carrie XSLT is short for Extensible Stylesheet Language Transformations . It is a programming language used to transform XML from one syntax to HTML, plain text, or another XML syntax, etc. For example. Lets say you have an XML file that looks like this: Hello World Lorem Ipsum . . . You can use XSLT to transform it to the following HTML: ... Hello World Lorem Ipsum . . . This is an XML technology, not a structured Frame technology, but you can incorporate it with structured Frame. Mike -Original Message- From: framers-bounces+mike.feimster=acstechnologies.com at lists.frameusers.com [mailto:framers-bounces+mike.feimster=acstechnologies.com at lists.frameuse rs.com] On Behalf Of Carrie Baker Sent: Monday, May 21, 2007 1:08 PM To: Scott Prentice Cc: framers at lists.frameusers.com Subject: Re: Getting data from xml into Frame was,Do I need to jump into the Structured FM pool? 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.
Re: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
See also: http://www.w3schools.com/xsl/default.asp Yves Barbion Documentation Architect Adobe-Certified FrameMaker Instructor Scripto bvba Asselsstraat 65 9031 Gent Belgium T: +32 494 12 01 89 F: +32 9 366 50 32 BTW (VAT) BE 0886.192.394 skype: yves.barbion Mike Feimster wrote: Carrie XSLT is short for Extensible Stylesheet Language Transformations . It is a programming language used to transform XML from one syntax to HTML, plain text, or another XML syntax, etc. For example. Lets say you have an XML file that looks like this: Hello World Lorem Ipsum . . . You can use XSLT to transform it to the following HTML: ... Hello World Lorem Ipsum . . . This is an XML technology, not a structured Frame technology, but you can incorporate it with structured Frame. Mike -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] rs.com] On Behalf Of Carrie Baker Sent: Monday, May 21, 2007 1:08 PM To: Scott Prentice Cc: framers@lists.frameusers.com Subject: Re: Getting data from xml into Frame was,Do I need to jump into the Structured FM pool? 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 <[EMAIL PROTECTED]> 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 F
RE: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
Carrie XSLT is short for Extensible Stylesheet Language Transformations . It is a programming language used to transform XML from one syntax to HTML, plain text, or another XML syntax, etc. For example. Lets say you have an XML file that looks like this: Hello World Lorem Ipsum . . . You can use XSLT to transform it to the following HTML: ... Hello World Lorem Ipsum . . . This is an XML technology, not a structured Frame technology, but you can incorporate it with structured Frame. Mike -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] rs.com] On Behalf Of Carrie Baker Sent: Monday, May 21, 2007 1:08 PM To: Scott Prentice Cc: framers@lists.frameusers.com Subject: Re: Getting data from xml into Frame was,Do I need to jump into the Structured FM pool? 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 <[EMAIL PROTECTED]> 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. > &g
Re: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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 <[EMAIL PROTECTED]> 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 r
Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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
Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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
Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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 re
Re: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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
Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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
Re: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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
re: Getting data from xml into Frame was, Do I need to jump into the Structured FM pool?
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 [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
