Sarah O'Keefe, author of FrameMaker 7: The Complete Reference and other books on technical writing, described how to create FrameMaker Element Definition Documents , the FrameMaker DTD application. See her white paper at www.scriptorium.com/structure.pdf.
Sarah divides documents into three types based on their level of structuring.
| Type | Example | Characteristics |
|---|---|---|
| Unstructured documents | QuarkXPress document | Look and feel. "It's all presentation. No points for technical merit." |
| Semi-structured documents | FrameMaker or Word with consistentlytagged styles. | Look and feel. "Use tags to organize the look and feel. Presentation counts, but tagging is important." |
| Structured documents | FM Structured Document, XML | Determine hierarchical tagging structure based on content. Formatting based automatically on structure. |
If you are accustomed to working stringently with paragraph styles in FrameMaker or Word, moving on to XML is conceptually not too difficult. With structured documents, nothing is "Normal" anymore. You can use any tags you want in your document structure. Everything in the text is tagged hierarchically, so that it can be demonstrated in a tree structure. The tagged sections are known as elements . Elements can be further specified with attribute s, which are called metadata in FrameMaker.
When designing template s, it is very important to "Plan from the top down, but implement from the bottom up." Analyze your material and divide into into a reusable hierarchical structure, where child ren elements are nested within their parent s as in the following structure for an article or book:
A chapter has sections, which contain paragraphs, which may contain words that are marked to be emphasized. Note that both a chapter and a section could have a title child, and that a chapter could have several sections, and a section several paragraphs (or even sections). Everything nests within each other. You can use the same Title and Section definitions, even if they are used in different levels of the hierarchy. You might want to diagram the structure first. Think of all the different instances of your document type to make it as generic as possible.
The tricky part of a structure template is deciding which metadata ( attributes ) to use to further define the elements. In some cases you might want to use sub-elements, in others, attributes. For example, a document type may have a number of sections that are always the same, for example, Concept, Procedure, Example, Summary. You could make a very specific DTD that has separate elements for each of these types. Or you could have a structure where the Section elements have and atribute called "content", which can be specified to be one of the four types. Each application is different. It is up to you to decide what level of structure you want. "Add metadata when communicting additional information (often formatting) not required by the structure, or to add another dimension to the content."
When you have thought out your structure you can build the EDD. This is done in three steps:
The last item requires a decision. If you include formatting information in the EDD, you limit its usefulness. If you only expect to use the document in a single format type, such as printed, or HTML, then it is a possibility. But to keep your options as open and flexible as possible, Sarah O'keefe recommends that you use separate formatting templates for the different applications. This provides much easier maintenance of the formatting and separates structure architecture from formatting, which may also be done by different designers. It is rather the same distinction with using inline formatting in HTML or separate .css stylesheets for a whole site.
Sarah O'Keefe concluded her session with a question: "What are the three most important considerations in building structured templates?" She answered herself:
