🚀 go-pugleaf

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