🚀 go-pugleaf

Hi Michael...

I'm sure you'll get a lot of replies to this post .. with lots of different opinions. Here are mine ..

- Make sure you really have a reason for using XML .. there are good reasons to use XML, but there are also bad reasons to use XML. If using XML will result in a real tangible benefit to your workflow .. then it's probably a good idea.

- There is no real "should" for how XML is best used. It is popular to use XML for short topics .. this is an efficient way to develop and maintain modular documentation. But it really depends on what type of documentation you produce .. many people don't really need modular documentation.

- Unless you *really* need to develop your own XML data model, I'd recommend trying to use an existing model. The two popular documentation-related XML models are DITA and DocBook. DITA is a topic-oriented modular model (but can be used in a section or chapter model as well). DocBook is generally more of a chapter-based model (but can be used in a topic oriented way as well). Using an existing and popular model will save you a huge amount of time .. developing your own model can be rewarding and a good learning process, but unless you really want to sign up for maintaining this into the future (which can be a lot of work), I'd take a serious look at existing models.

- I wouldn't create a separate mode for each "piece" of your documentation .. I'd develop something that allowed it all to fit together. Again .. learn about the existing models (DITA and DocBook) and you'll learn a lot.

- Regardless of what you do, if you're using FrameMaker, you'll need to carefully read the Structure Application Developers Guide .. this is your guidebook and bible for XML development with FM.

Cheers and good luck!

...scott

Scott Prentice
Leximation, Inc.
www.leximation.com

I'll second Scott's fine summary.

Hi Scott,

Thanks for the information. I will check out the DocBook and DITA Web sites and the structured dev guide. I'm a technical writer for a software company. Our products come with installation guides, administrator's guides, and online help. The information contained in the adminstrator's guides is the same information that is contained in the online help. The content is just broken up differently. Our products use the same technology, different configurations, so the opportunity for reuse if pretty good.

I would like to be able to create the content once and then generate the different types of output (pdf, html, etc...) for the different products and guides. What I'm doing now isn't company sponsored, I'm doing it on my own time, but I'm sure that if the results turned out good that they would look into it. I've been studying XML so that is the reason that I was looking towards an XML solution.

Anyway, thanks again for the information. If you think of anything else or any other resources, I would be happy to hear about them.

Michael Randall

Hi Michael...

If you're using FM8, it comes with built in support for DITA as well as an XDocBook structure application, so you can play with both models. If you're using FM7.2 or FM7.2, you can download a "lite" version of DITA-FMx (version 0.0 is free) .. or you can try the full version of DITA-FMx for FM7.2 or FM8 (http://leximation.com/dita-fmx/).

DITA is supported by a set of XSLT and Java tools called the DITA Open Toolkit (DITA-OT), which lets you generate 9 different types of output from DITA XML files. I have a website where I provide links to the official DITA sites as well as some useful links for more info.

 <http://www.ditamap.com>

Best of luck with your project!

...scott

Scott Prentice
Leximation, Inc.
www.leximation.com

Michael,

Let me express a different perspective.

* It may be obvious, but the relationship between structured FrameMaker documents and XML documents should probably be stated. Both consist of a hierarchy of elements, each consisting of some combination of other elements and text. Attributes (named strings) can be associated with elements. There are rules for which elements and attributes are allowed and required where, and the possible values of the attributes. This commonality is such that it is straightforward with most XML models to move material back and forth between FrameMaker and XML views.

While it is possible to define an XML structure in which the elements and attributes specifically define formatting conventions, the typical XML document focuses on the division of a document into logical units such as those you give in your examples. FrameMaker adds to the element structure, context-sensitive format rules that automatically apply FrameMaker formatting such as paragraph and character formats. Thus, in many applications, there is no need (at least within FrameMaker), for attributes such as the number attribute you show for the <step> element, because FrameMaker autonumbers will provide consecutive numbering. Furthermore, FrameMaker recognizes that some elements correspond to special formatting objects such as anchored frames, markers, or cross-references.

Since XML and structured FrameMaker use the same underlying model, you can design your tagging scheme with either. Working with FrameMaker first, where you can perform WYSIWYG editing, may be easier.
* I agree with Scott that existing applications often provide a good starting point for developing an application. However, tagging schemes such as DITA and DocBook are deliberately designed to be flexible enough to express documentation used in a large number of organizations. They therefore define many more elements and attributes that any one organization may use. Furthermore, they do not enforce all conventions that an organization may wish to enforce.

Unless you already have experience working with either XML or structured FrameMaker, you may want to start to gain that experience with a simpler model. There are several such examples in <installdir>\structure\xml (where <installdir> is the directory in which FrameMaker is installed, typically c:\Program Files\Adobe\FrameMaker8). (The training material I mention below, also includes examples.)
* Anyone who is going to set up an application of structured FrameMaker needs to be familiar with the Structure Application Developer's Guide. However, the Dev Guide assumes that the reader is already familiar with structured editing and XML. If you don't have this background, the Dev Guide can be overwhelming.
* There are three sets of skills needed to develop an XML application in structured FrameMaker: understanding of structured documents, ability to set up a structured environment within FrameMaker, knowing how to configure the correspondence between structured documents and XML documents. Since each is a prerequisite for the next, it helps to learn them in the order listed.


This is not an advertising site, but I hope it is not inappropriate to mention that my company does offer a self-study license to our course materials on structured authoring. This class is intended primarily for users who are already familiar with FrameMaker's original user interface and want to learn structured authoring. It does not cover configuring structured FrameMaker (which is the subject of the Dev Guide). Contact me directly at lprice@txstruct.com if you are interested.

--Lynne