Chapter 5. Document Type Modeling and Specification

Table of Contents

5.1. Preparing for the Modeling Work
5.2. Performing the Modeling Work
5.2.1. Step 4: Selecting Semantic Components
5.2.2. Step 5: Building the Document Hierarchy
5.2.3. Step 6: Building the Information Units
5.2.4. Step 7: Building the Data-Level Elements
5.2.5. Step 8: Populating the Branches
5.2.6. Step 9: Making Connections
5.2.7. Step 10: Validating and Reviewing the Design
5.3. Producing the Document Analysis Report
5.4. Updating the Model

The goal of the modeling and specification phase is to peruse all the potential components and to turn them into a specification for an exhaustive and coherent markup model for the document type. The output of this phase is a document analysis report that records both the specifications for the model and the process undergone to reach them.

Chapter 4, Document Type Needs Analysis explained how the design team identified potential needs and classified them into logical categories. This chapter takes the team through the design and reporting portions of the work, which include:

We continue to assume a project where a new document type design is being created. For information about the process of customizing an existing model and how it compares to the process for a new DTD, see Section 7.1, “Customizing an Existing DTD”. Chapter 6, Modeling Considerations offers specific advice about modeling considerations.

5.1. Preparing for the Modeling Work

Unlike the analysis phase, where all ideas and suggestions are welcome and studied with interest, the modeling phase involves making choices and decisions. It can be a difficult time because it generates a number of conflicts, with each member having a personal interest in backing his or her ideas. At this point, it may be useful to reaffirm the decision model under which you operate.

Team members need to consciously keep an open mind and remember that anybody's requirements, as long as they are properly supported, are likely to become requirements at some point for the departments that the other team members represent.

At the same time, you need to avoid the effects of a design team that is too cohesive—exhilarated by their work and their power to model all future documents, so that they want everybody in the company to work the way they decided. DTDs are not perfect models to be admired in a rarefied atmosphere, but tools to be used daily by people in the field, whom the team members have a responsibility to represent.

As a consequence, purity may have to give way to efficiency and theoretical principles to be replaced by down-to-earth, practical recommendations. Team members will need to abandon their fond hopes of imposing their personal views of writing style through the DTD. (Section 6.4, “Strictness of Models” discusses some ways to test whether a proposed model is too prescriptive.)

These efficiency-driven attitudes must be recorded in new principles each time a general rule is formulated for how decisions must be made. As you will find out, the number of principles will grow significantly in this phase of the work, but it will also significantly help the decision process because you will actively be ranking the various tradeoffs, for example, the opportunities for consistency versus the intuitiveness of a model.

Of course, your principles must reflect the project's overall goals. At this stage, it is useful to remind the team members of what those goals are. For instance, if the company intends to switch to electronic distribution, whether on CD or online, and a marketing survey shows that customers expect no less than state-of-the-art multimedia features, any team member claiming that “we do not need a video element because we have never produced a minute of video in this company” is wrong. The company intends to do it in the near future and will need hooks for incorporating its video clips within documents.

Similarly, the team needs to remember the constraints weighing on the project and integrate them in their decision process. For instance, if the company has decided not to build any kind of document management system and expects each author to handle his or her own work on a workstation, then the granularity of the DTD will probably have to be the book or the manual, and cross-document cross-referencing becomes useless. Also, if the company has a very strict policy on labeling safety or security information, then the team would need to ensure that automatic label generation is enabled by the chosen markup model. (Section 6.7, “Generated Text” discusses some of the complexities of preparing for generated text.)

The role of the facilitator will become ever more challenging as the work progresses. It will be crucial for the facilitator to make sure that all members have a chance to express their opinions, that decisions are made after each discussion, and that work keeps to the schedule without the constant revisiting of decisions. The role of the recordist is also more complicated because discussions are likely to be animated and complex, and this person must not only record the gist of the discussion, but also make it understandable for nonspecialists and ensure that all relevant points are transcribed faithfully and completely. Team members should review the interim reports between meetings, if possible, and offer corrections at the next meeting.

5.2. Performing the Modeling Work

Up to this point, the team members have catalogued the potential semantic components by defining them, classifying them, and validating them against other analyses that have been done. Thus, the upper half of all the component forms is complete. To keep track of all the information collected during the modeling phase, the team will fill in the bottom half of the component forms, and will also use tree diagrams (described thoroughly in Appendix B, Tree Diagram Reference) and some new forms, the main one of which is the element form. We'll introduce the others as we go along.

Element forms keep track of information on the modeling of the elements. Along with the component forms, the element forms will be later assembled into the document analysis report, and when all the fields are complete, will provide a historical record of the design in the final report and a reliable basis for the writing of the DTD's reference manual.

The element form can be thought of as a continuation of the component form, particularly in cases where an accepted semantic component is represented directly by a single whole element type in the resulting model. Each element form refers to its corresponding component forms by their numbers to avoid duplicating relevant information, and it is fully filled out only after the actual DTD is implemented, so that information such as the generic identifier (the “tag name”) can be filled in.

Figure Figure 5.1, “Element Form” shows a blank sample of an element form.

Figure 5.1. Element Form

Element Form

The following explanation of the fields also serves as a map for the modeling work. In the following sections, we will refer regularly to the element form and give examples of how it can be filled in.

Field When Filled In Description
Element name Steps 5 through 8

The full name of the element; a phrase of arbitrary length that describes it uniquely.

Number When the element is stable

A number given to be able to cross-reference from and to the corresponding component forms.

Generic identifier After DTD implementation

The generic identifier; the short form of the element name that is actually used in tags.

Class(es) Steps 5 through 8

The one or more classes into which the element falls. Make sure to include its superclass: document hierarchy, information unit, data-level, link, or special.

Model/Contains Steps 5 through 8

A concise and clear description of the internal structure of the element, plus the corresponding tree diagram if appropriate.

Rationale Steps 5 through 8

All the reasons why the element was modeled this way, including, for example, why “wrapper” elements were created or not, and why subelements were optional or not.

Is contained in Steps 5 through 8

A description of where the element can be found elsewhere in the model. It can be expressed in words with a list of parents, with one or more tree diagrams if the number of parents is very limited, or with a table when the potential contexts are numerous. Many elements will not have an answer for this field until step 8.

Refers to components Steps 5 through 8

The numbers of the component forms where the initial semantic components that this element represents were thoroughly described. This field helps to avoid duplicating useful information.

Creation/change history Maintenance phase

The date the form was first filled in, and the dates and brief descriptions of subsequent changes and additions.

By the end of step 3, the team members have a list of semantic components to choose from and a number of tools to help them formalize their modeling work. They can now move to step 4, where they choose which semantic components should be kept.

5.2.1. Step 4: Selecting Semantic Components

The design team needs to select, out of the original compiled list, the components that represent markup distinctions needed for the project at hand. To do this, the team members will probably need to make a couple of passes over the list, taking care of the easy cases first. Throughout this process, the facilitator and recordist must work in tandem to ensure the results are fair, swiftly accomplished, immune to rediscussion, and recorded.

To make a first pass, examine the entire list of potential semantic components and select all the components that are obvious ones to be kept. For each component, the team must be able to formulate a rationale stating why this component should be kept in the model. If a component is just too obvious and the only rationale people can think of is, “Because we need it,” make sure an example has been given that demonstrates the necessity of the component.

During the review of the list, some components will seem obvious to some members and absolutely not to some others. If agreement cannot be reached within a time limit of five or ten minutes, just drop the subject and defer the contentious cases momentarily.

By the time the list has been gone through once, usually fewer than twenty percent of the components remain for a closer analysis. At this point, it pays to be highly methodical and disciplined. For each component on which the team does not agree, the team should consider the following factors based on the design principles.

  • Fits Within Scope

    Is the component within the defined project scope? If not, don't go any farther; reject the component. If a more ambitious project is undertaken later that includes the component in its scope, the analysis done to date will be a useful starting point.

  • Isn't Too Presentational

    Is the component too presentation-related to be kept? A component might be a holdover from a previous markup system that gave authors inappropriate control over appearance (such as “centered text”); these should be discarded. Or, it might be a presentational interpretation of a legitimate component (such as “title page”); these should be recast to be more structural or content-based. Or, it might be a processing or formatting function that authors must have control over; these should be kept and their purpose explained thoroughly. They will probably end up being addressed in step 9.

  • Enables Project Goals Today or Tomorrow

    Can a team member show examples of where this component is necessary to have today? For example, do instances of information described by this component look different from all other similar kinds of information, or does it need to be uniquely searched on?

    If not, can someone explain a legitimate future use of this component? The trick here is to be realistic; don't rely on fanciful imagined uses.

    The component selection step often forces the realization that two or more components, which have survived so far as unique items, have differences between that are so minute that examples can't be found to differentiate them. In these cases, the two components should be collapsed into one and then accepted as a single component.

    For the few really tough cases where a decision can't be reached, try keeping the component and waiting for a further step to make a final decision when the team's process has matured. The team may decide to pose the question during testing and let the users decide for themselves.

Following are some results of the selection of components for the CookThis project. Most of the components are accepted because of their clear relevance to the task at hand; the few difficult cases and all the rejected cases are shown here.

Component Name Accepted? Rationale
Acknowledgments section Yes If individuals donated the recipes, they must be thanked. This section is different from the preface in that we like to give the names of these people prominence, and being able to uniquely identify the place where they are thanked will help us do so.
Recipe set introduction Yes People browsing a set on the CD-ROM will want to see an overview of the set before they open the whole thing. We can also extract these for other uses (such as marketing material).
Source of recipe Yes Even though the acknowledgments section will informally mention all these people, each recipe has to be able to “travel” sufficiently all by itself, when we produce the index cards. Thus, the source of each recipe (if known) should be provided with the recipe.
Recipe type Yes Knowing this information for each recipe will allow us to generate new sets based on different criteria.
Recipe preparation time Yes Busy people need to know this information, and it may be a search criterion.
Ingredient alternative No Many times, alternatives are just suggested casually in the text. Having a formal way of storing this information doesn't fit in with the way our recipes are structured or written. It would be too hard to get people to force recipes into the mold.
Instruction optionality Yes We clearly have many cases where a step can simply be left out. We hope to set off these steps somehow.
Instruction title No We debated this for a long time, but even though we have one or two clear cases of a seeming “title” on instructions, it's not appropriate according to our style. The text of each instruction should explain its special purpose, if any.
Number No It's obvious what a number is; any processor that had to operate on numbers could easily find them without their being marked up. As long as amounts are marked up, random numbers don't have to be.
Degrees No A degree setting is simply another kind of amount, so this is already taken care of. We'll remove degrees as a separate component and keep amount.
Unit of measurement Yes An amount is useless without the units it is expressed in. We need to be explicit about this information.
Oven setting No This is another kind of amount. This should be rejected because it is already covered.

At the end of this step, the list of potential semantic components bears a “yes” or “no” decision in front of every component name, and each component form bears the same information in the “Accepted” field, along with the reasons for that decision in the “Rationale” field. The rationale can be a plain explanation, an example of use, the reminder of a principle, or a mixture of all three. It must be clear, precise, and definite enough to prevent any impulse to revisit the decision. The recordist should also build a new list containing just the accepted components, for convenience in the rest of the steps.

With the list of accepted classified components, the design team holds the raw material for its future work. The team can now begin to work top-down to build a model that accounts for all the accepted components. To do this, the team members will iterate over the list of components, extracting from it all the components related to each distinct layer of the document type model, and then actually model them as elements and attributes using tree diagrams. These distinct layers are the “standard” superclasses that overlay your unique classifications. We'll introduce them individually at each step, so that you can concentrate on one layer at a time.

5.2.2. Step 5: Building the Document Hierarchy

The first layer to be modeled is the document hierarchy. The following sections describe the process of identifying and modeling the document hierarchy components and their related metainformation components.

5.2.2.1. Modeling the Document Hierarchy Components

The document hierarchy is our name for the class of components that represents the upper part of the document type. These components capture the essence of that type, and once they are modeled, they give a characteristic “shape” to every instance conforming to that model. As a consequence, authors usually have little choice about markup at the upper levels, though they may have a choice about how deeply to nest the basic divisions of content within the hierarchy.

The document hierarchy ends where “unspecified text” begins to appear—the locations where authors begin to have a great deal of freedom in how they structure and compose the content. (Unspecified text will remain unmodeled until step 8; we use “clouds” in tree diagrams to serve as unspecified text placeholders.) Some of the colloquialisms people use to describe this material are:

Stuff
Text
Prose
Real” content

Figure 5.2, “Identifying the Document Hierarchy Components” illustrates the document hierarchy concept.

Figure 5.2. Identifying the Document Hierarchy Components

Identifying the Document Hierarchy Components

The team has probably already grouped the document hierarchy components together, perhaps in a class called “structure” or “divisions.” In the CookThis analysis, this class had the name “cookbook structure.” If such a class hasn't already been identified, here are the criteria to find out if a component is part of the document hierarchy.

For technical manuals, academic books, and novels, and any other type of document that is large enough to have a table of contents, start by seeing what's in that table. What you usually find is the way the document is subdivided. Depending on the document, the table of contents may not represent all the levels of subdivisions that the document contains. To make sure, peruse the documents' actual contents and check all the subdivisions and organizational containers of the document that you encounter against your classified component list, until you reach places where unspecified text appears.

For documents that don't have tables of contents, the process of identifying hierarchical components can be trickier, because the hierarchy may seem surprisingly flat. For instance, if you look at a restaurant menu, you have to build the table of contents in your head because it is not provided in the document. However, the mental process is the same. In all cases, check for evidence of levels of structure that are above, below, and between the levels that you can easily see.

To take the restaurant menu example a little further, here's what you might find:

  • The obvious divisions might be for appetizers, entrées, desserts, and drinks.

  • The obvious subdivisions of entrées might include children's dishes, vegetarian dishes, chicken dishes, and so on.

  • There may be a nonobvious level of division at the top, if additional menus exist for desserts and wines and if they can sometimes be included together with the regular menu content.

Note that in this example, the components actually identified may have been structural (for example, “high-level division” and “low-level division”), or they may have been content-based (for example, “appetizer division” and so on). The discussion of levels can take place regardless of the component choices made. (Section 6.5, “Divisions ” discusses some of the issues in modeling divisions and their nesting.)

There are some documents whose hierarchy is basically flat because they present a collection of similar information that is grouped, for clarity's sake, in only one or two levels of hierarchy. For example, dictionaries, catalogues, indexes, reference manuals, and cookbooks usually fall into this pattern. According to the CookThis analysis done in Chapter 4, Document Type Needs Analysis, a cookbook's overall document hierarchy would include little more than large sets of recipes. The number of division levels would reach a maximum of two: recipe sets and the recipes themselves.

The act of identifying document hierarchy components will have started the modeling process. To formalize it, visualize the components as elements and attributes, working top down, using the tree diagram notation to help you. This is where a large whiteboard comes in handy, so that people can easily propose alternatives to a suggested model.

You will have finished the modeling work for the main part of the document hierarchy when all the branches of your tree end up with clouds representing unspecified text. You then need to record both the trees and the corresponding prose in the “Model” and “Contains” fields of a series of element forms, one for each element you have modeled.

In the CookThis cookbook model, the bulk of the document hierarchy might ultimately be described by the tree diagram shown in Figure 5.3, “Initial Cookbook Document Hierarchy”. This diagram shows nearly the entire structure except for recipes themselves and except for the “metainformation” element, we'll we'll defer to Section 5.2.2.2, “Modeling the Metainformation Components”. Note that where an element appears multiple times, its potential model is shown in only one place; in all its other locations, an ellipsis serves as a placeholder for its model.

Figure 5.3. Initial Cookbook Document Hierarchy

Initial Cookbook Document Hierarchy

Figure 5.4, “Initial Recipe Document Hierarchy” shows the detail for the recipe element's model (minus its “metainformation”). Also note that the main contents of recipes are deferred for now because they appear in other classes, and will benefit from the general treatment given those components in a future step.

Figure 5.4. Initial Recipe Document Hierarchy

Initial Recipe Document Hierarchy

This recipe structure may seem obvious, but it's worth pointing out that the results might have been very different if the recipes had used a different style. For example, one common recipe style is as follows:

Boil 1 cup of rice in 2 cups water. Season with salt...

In general, you don't have to worry about all the structures your information could have used, just the ones it does use, so in the case of CookThis, this new style doesn't have to be accounted for. If your project requires that you acount for the widely diverging organizations of content, you may want to create a separate model for each one in order to maximize the information's usefulness for various purposes.

The following table shows the filled-in “Element name,” “Contains,” and “Rationale” fields for the elements shown in Figure 5.3, “Initial Cookbook Document Hierarchy”. The following fields also need to be filled in:

  • In the component forms associated with the document hierarchy, fill in the SGML markup/related elements field with a precise description of the markup that resulted from each accepted component and list the numbers of the relevant element forms.

  • In the element forms, also fill in:

    Number
    Class(es)
    Is contained in
    Related components
Element Contains Rationale
Cookbook

A cookbook contains a required metainformation block, followed by a single optional preface and a single optional acknowledgments section, followed by one or more recipe sets, followed by zero or more appendices.

The metainformation is needed to identify the cookbook.

The prefatory material and acknowledgments may not appear in any one cookbook.

Our children's cookbook will have only a single recipe set, so we only need to require one. If there were zero, the cookbook would be empty of main content.

Any one cookbook might have no appendices or one or several.

Metainformation

The metainformation contains at least the recipe title.

The metainformation is at the beginning for convenience of processing. (More on metainformation in Section 5.2.2.2, “Modeling the Metainformation Components”.) It was decided that a container is needed to group both the descriptive information and the legal information, so that all this material will be stored in a single, easily accessible place and we can build markup templates for it for authoring convenience.

Title

A title contains unspecified text for now.

The same title element is used to label several different elements: recipes, recipe sets, appendices, recipes, and ingredient sublists. The reason is that the context (the immediate parent) can easily distnguish them all.

Preface

A preface contains unspecified text for now. It is expected to have a generated label.

Since there can be only one preface and its label (“Preface”) is dictated by the corporate standards department, this element needs no title element; we have the ability to generate a label for the preface automatically, which will allow it to be absolutely consistent across cookbooks.

Acknowledgments

An acknowledgments section contains unspecified text for now. It is expected to have a generated label.

Since there can be only one acknowledgments section and its label (“Acknowledgments”) is dictated by the corporate standards department, this element needs no title element; we have the ability to generate a label for this section automatically, which will allow it to be absolutely consistent across cookbooks and spelled correctly every time.

Recipe set

A recipe set contains a required title, followed by a required introduction, followed by one or more recipes. Recipe sets aren't expected to be numbered.

The title is required to label the sets, since there can be more than one.

The introduction is required, so that the reason for this particular grouping of recipes will be explained to the reader.

In rare cases, such as in the Elephant Meat set in the planned Exotic Cookbook, only one recipe may currently exist in a set. At least one is required, though, or else there's no point in having a set.

Appendix

An appendix contains a required title, followed by unspecified text for now. Each appendix is expected to be numbered.

The title is required to label the appendices, since there can be more than one.

There are no cases of appendices that have a complex internal structure; they all just contain their main content straightaway.

Introduction

An introduction contains unspecified text for now.

No label is needed on an introduction, since by definition it introduces the content of the element it's in (recipe set or recipe). The same introduction element is used to label several different elements; the context (the immediate parent) can easily distnguish them all.

Recipe

A recipe contains a required title, followed by optional source information, followed by an optional introduction, followed by a required ingredient list and a required instruction list, followed by zero or more notes.

The title is required in order to distinguish recipes.

The introduction is optional because sometimes there simply isn't anything to say.

Even the simplest recipe has at least one ingredient, so a formal list should be present to help the reader know what to assemble.

Likewise, even the simplest recipe has at least one instruction, so a formal instruction list is required.

Some components that were identified as being in the document hierarchy haven't yet been accounted for in the CookThis model: the ones that describe characteristics of a cookbook or recipe itself. These are covered in Section 5.2.2.2, “Modeling the Metainformation Components”.

5.2.2.2. Modeling the Metainformation Components

Metainformation is information about information. For example, the metainformation for the book you are reading now might include its title, its price, its authors, its publication date, and so on—everything except its actual content about developing DTDs. Likewise, in a cookbook, everything related to cooking techniques, utensils, and recipes is content. The information about the cookbook as a publication or as a body of information is metainformation. This includes the information that appears on the cover and title page, as well as navigational devices such as the table of contents.

Metainformation isn't simply “everything at the beginning of a book”; it can include all sorts of information that might appear at the end or in other places, such as summaries, certain kinds of back matter, bibliographical references, and an index.

Also, metainformation isn't just “everything about the book as a whole.” Smaller pieces of information can have their own narrowly scoped metainformation, too. For instance, a top-secret security status might apply to a whole technical manual, but it might also apply to only a single paragraph or section. Similarly, a manual can have a global abstract, but it might also contain an abstract for each chapter. Thus, each time the design team models information content, they must make sure to model the related metainformation and to keep this approach even when modeling the subdivisions of a document type and other elements.

In the CookThis example, metainformation can potentially be found at the following levels (some of which have already been modeled):

  • Cookbook metainformation:

    • Title

      Not everyone considers titles to be metainformation; because they are always output in each presentation instance, they act like real subject matter content themselves. But in the sense that they describe content, they can be considered metainformation.

    • Cookbook descriptive information with the cookbook title and the editor

    • Legal information with the cookbook copyright and trademarked term attributions

    • Preface

      Some people consider a preface to be metainformation because it introduces the rest of the document and thus serves a “meta” function. However, it also often contains real subject matter content. Like titles, prefaces have one foot on each side.

    • Acknowledgment section

      Like titles and prefaces, acknowledgment information can be seen both ways.

  • Recipe metainformation

    • Title

    • Source of recipe

    • Recipe type

    • Recipe copyright

Once the team has identified all the metainformation components, it must model them as elements and attributes and fit them into the rest of the document hierarchy, considering whether each component makes sense at multiple levels of the structure.

It often seems, on first reflection, that metainformation components should always be represented by attributes, since a piece of metainformation “qualifies” or further describes the document element or a lower-level element. However, if the information is likely to be output along with regular document content (as titles usually are), representing the component with an element is usually the better choice, and if the information must itself contain markup, an element is the only choice. Any metainformation that records one of a set of finite states, such as a draft status of “in review” versus “complete,” is a natural candidate for an attribute.

Often, the DTD implementor is the person best suited to choose for each metainformation component the best expression in SGML markup, based on your description of what the metainformation will be used for. Thus, it's especially important that you record, along with your modeling recommendations, the processing expectations for the metainformation. For example, if you expect part numbers to be checked by the document management system to ensure that certain fields in them have valid values, say so; the implementor may decide to use attributes to hold the different fields, with “data types” (declared values) that constrain the values so that they can be validated by parsers without development of additional software.

Because metainformation is by its nature outside the flow of document content, usually the position of its output is variable, that is, it can change according to the media. For example, in paper form, legal notices might appear on a copyright page that appears behind the title page, but in a hypertext document, a special menu item might exist for legal notices, and there might be links from every occurrence of a trademark to its related legal notice for the trademark attribution. Because of this fact, the order in which metainformation is supplied in the SGML document instance is less relevant than for the document subject matter, over which authors typically have at least some control. Therefore, the best way to model metainformation is to choose a single location where it will reside in each level of division.

To ensure that metainformation is always identifiable in instances and can be used efficiently by processing applications, it's best to put metainformation before the information to which it applies, so that the document can “tell a processing application what it's going to tell it” before it actually “tells it” what the content is. This scheme allows even the simplest applications to prepare in advance for manipulating the coming content. For interchange, it is especially useful to model metainformation elements in a fixed order, so that a wide variety of interchange partners can build different applications that reliably find all the metainformation they need and output it (or transform it to a reference DTD) in their own unique order and style.

Figure 5.5, “Complete Cookbook Document Hierarchy” shows a complete tree diagram for the document hierarchy of the cookbook document type, including recipes and metainformation.

Figure 5.5. Complete Cookbook Document Hierarchy

Complete Cookbook Document Hierarchy

The rationales for the modeling choices are as follows. Most of the cookbook metainformation has been put into elements because it is highly textual in nature, and may need to be further marked up. A container element has been added to hold all the names of the editors, so that the information can easily be retrieved all at once. The trademark and copyright information has also been grouped into a container element for the same reason. Some of the recipe metainformation is in attributes, and some in elements. The attributes can be used to ensure that the values supplied are acceptable to the retrieval and formatting systems. (Step 9 may give rise to additional metainformation, such as ID attributes, that may appear on multiple elements.)

Note to DTD Implementors

If you implement metainformation as attributes, put the attributes directly on the elements to which they apply (for example, the top-level cookbook element), not on any special metainformation containers (such as the metainformation element in this example). Processing applications generally make it easier for lower-level elements to “inherit” attribute values from a parent element than from an unrelated element that appears before them in the linear flow.

5.2.3. Step 6: Building the Information Units

When the design team starts step 6, the members know what the overall hierarchical structure of the document type is like, and they have a sorted list of all the rest of the components. Most of these remaining components are related to the information pool, the collection of elements from which authors choose, largely at their own discretion, in marking up, organizing, and composing the “main content” of documents. In identifying the components in the information pool, you will gradually turn the large cloud in Figure 5.2, “Identifying the Document Hierarchy Components” into organized classes and subclasses of elements, as shown in Figure 5.6, “Identifying the Information Units in the Information Pool”.

Figure 5.6. Identifying the Information Units in the Information Pool

Identifying the Information Units in the Information Pool

As the figure shows, the information pool tends to break down into two layers: the components associated with information units (IUs)[9], and the data-level components . This step deals with IUs and step 7 deals exclusively with data-level components, but we'll define them both here.

An IU is a high-level component that can, to some degree, “stand alone” in order to be understood by a reader, such that its content must “travel together” during information processing and assembly. IUs also typically have a complex internal structure (represented in Figure 5.6, “Identifying the Information Units in the Information Pool” by a small tree diagram), and thus need to be modeled with their associated subcomponents in mind; for instance, all subcomponents related to a list would be modeled together. Even when the internal structure of an IU is more complex, like a procedure including several steps that each list several instructions, you still know that the procedure must be considered as a whole to be correctly interpreted.

By contrast, data-level components are small important bits of information that need to be processed or handled differently from the surrounding character data for some reason. These bits of information, all by themselves, would be meaningless without their context, which almost always consists of prose. They rarely have any complex internal structure.

IUs are sometimes called “displayed” or “block” information and data-level components are often called “inline” information. However, these presentation-based descriptions may be confusing and inconsistent rather than helpful; it's possible, though relatively infrequent, for some components to be part of both the IU class and the data-level class.

The design team needs to peruse the list of components and extract those that it considers unique IUs, along with all the components that are obviously subparts of those IUs. Then the team can build a classified list of all the identified IUs and rebuild a list of the rest of the components to work from in the next step. Then the team needs to model the IUs in each class in turn, deciding how many elements will represent all the IUs and determining what the models for those elements are using tree diagrams. If any metainformation was discovered in the previous step that might apply to pieces of information that are smaller than the whole document, now is the time to apply them to the resulting IU markup.

Particularly in the areas that are specific to your information domain, IU modeling work is highly creative. Content-based IUs are the most interesting, but even the relatively structural components may surprise you with their controversies, and we hesitate to recommend a single paragraph, list, or quotation model to you because your situation may have special needs and constraints. Chapter 6, Modeling Considerations covers many common modeling problems and possible solutions.

The CookThis example is a simple case; the design team has determined that the following classified IUs should each be represented with its own element:

  • In the list class:

    • Ingredient list (with ingredient sublist, title, ingredient, and ingredient optionality)

    • Instruction list (with step and instruction optionality)

    • List (with list item)

  • In the text-based class:

    • Note (with note title)

    • Paragraph

  • In the picture class:

    • Illustration (with caption)

    • Photograph (with caption)

  • In the table class:

    • Table (with the CALS table model)

Describing the internal structure of a few common IUs can be quite easy because their structure is essentially flat. For instance, a paragraph usually immediately contains unspecified text. Most IUs are more complex and require some thought and careful recording, because there are several possible ways to structure them.

In our CookThis example, it turns out that the ingredient list IU has a relatively deep structure: An ingredient list can contain a mixture of ingredients and ingredient sublists, and the sublists can optionally contain a title and must have a minimum of two ingredients. Each sublist has an optional title and is composed of at least one ingredient. Ingredients contain unspecified text and have an “include” attribute, whose default is that the ingredient is required to be included in the recipe. The tree diagram for an ingredient list is shown in Figure 5.7, “Tree Diagram for Ingredient List”.

Figure 5.7. Tree Diagram for Ingredient List

Tree Diagram for Ingredient List

Note that some IU components might ultimately be represented by the same element, only in different contexts or with an attribute to distinguish them. For example, it might be decided that illustrations and photographs are functionally the same kind of document information. If you want to collapse some IUs completely, remember that you have already justified keeping the distinction between them; look at your step 4 rationale for keeping the two components to remind you of why it was so important to have two instead of one. If you do collapse them, make sure to update your component forms. (Section 6.1, “Distinctions Between Components” discusses some strategies for representing multiple related components.)

When all the IUs have been tackled, the design team needs to record, in words and with tree diagrams, the internal structure of the IUs and the reasons why such a model was designed. If the model is based on specific processing expectations, such as “There is no title on our examples because the title is always the same and will be generated,” then these expectations should be recorded too so that application developers will know what to do and interchange partners will know how to interpret delivered SGML documents. Along with filling in the “Contains” and “Rationale” fields of the element forms for each element created, the recordist should cross-reference the element forms with the component forms.

5.2.4. Step 7: Building the Data-Level Elements

The starting point of step 7 is the list of remaining components, out of which the design team must extract, refine the classifications of, and model the components at the data level.

To reiterate the criteria for data-level components, they need surrounding character-data context (usually a sentence) to make any sense, and they must be associated with some intended processing or special handling.

Some potential processings of data-level components include:

  • Simply formatting a word or phrase in text differently, in order to set it off (for example, general-purpose emphasis or “verbatim” text)

  • Giving a certain presentation to phrases according to their meaning (for example, file names, product names, and trademarked terms, which must be distinguished from the surrounding material and from each other) or according to custom (for example, dates, measures, addresses, and honorific titles, which as a result may need special treatment in translation to other languages)

  • Automatically linking words or phrases with associated information (for instance, linking all the command names in a computer user's guide with the corresponding modules in the reference manual, or linking glossary terms in text with their definitions)

  • Building or assembling parts of documents based on the words or phrases found elsewhere in the document (for example, building the glossary based on the presence of glossary terms actually used in the document, or building a paper or online-retrieval index based on special technical phrases identified in the document)

(For now, the team should defer components that are exclusively related to “linking,” as well as any stubborn components that are highly presentational in nature. Both of these kinds of components will be addressed in step 9.)

Often, more data-level components will have been accepted in step 4 than are practical for authors to use, a situation that is a major contributor to Tag Abuse problems. Now that the data-level components have been through a few rounds of analysis and classification and the modeling process is well understood, an additional “elimination round” may be necessary.

To identify only those components that have a purpose, whether immediate or planned for the future, make sure as you model each component that it has unique processing expectations, that is, that the distinction made in the markup has a legitimate use. If some components fail this test, they can still be rejected or collapsed with others at this stage—and, of course, their component forms should record the decision and the rationale.

There are usually two subclasses of data-level components:

  • The relatively “structural” components that can be found in most document types

    For example, brief quotations and emphasized phrases typically fall into this class. (Since their internal structure is usually minimal, it might be better to call them “publishing-oriented” in this instance.)

  • The relatively content-based components, which have an intrinsic meaning and are usually specific to the domain of activity described by the document type

    For example, for a series of books on gardening, there might be components for soil depth measurements and the names of insect and plant species. We call this class the key data components. Describing the processing expectations for these components is especially critical, since much of what makes a document type uniquely useful for processing is its body of key data components.

There may also be outright presentational components at the data level, such as “font control” or “bold,” that have made it to this stage of the proceedings. If you have a good rationale for keeping them, defer dealing with them until step 9.

In the Cookbook example the list of accepted data-level components (“significant data”) might now be subclassified as follows:

  • General data:

    Trademarked term
    Recipe cross-reference (which we'll defer for now)
  • Key data:

    Unit of measurement
    Amount

As was done for the IUs, the team must determine how the data-level components correspond to elements and attributes and design their internal structure. Most data-level components actually don't have any complex internal structure; they can be designated as containing “unspecified text” directly. A few may have structure, though. For example, if the team is considering how to model a data-level mailing address, it may construct an address element that directly contains a series of subelements for addressee name, street number, street name, city or town, postal code, and so on, which may all finally contain unspecified text.

The CookThis team has modeled the data-level components as shown in Figure 5.8, “Tree Diagrams for Recipe Data-Level Components”.

Figure 5.8. Tree Diagrams for Recipe Data-Level Components

Tree Diagrams for Recipe Data-Level Components

The trademark component has been realized as an element, and some optional attributes describing the type of trademarked term have been added so that the term can be properly attributed with a generated symbol (for example, “” for unregistered trademarks). The type and registration status were not originally components, but discussion has brought out a need for them, and new component forms should be added to ensure that they are sufficiently defined and justified.

The amount component has also been realized as an element. The component for unit of measurement has been realized as a required attribute on the amount element, with the processing expectation that the chosen unit will result in the appropriate generated text before or after the amount (for example, “Tbs.” for tablespoons). The reasoning was that this approach will result in editorial consistency.

Note to DTD Implementors

The list of attribute values for the “amount” element is incomplete. This is a common situation with the modeling of attributes, and it will require you to investigate the boundaries of the list. See Section 8.3, “Handling Specifications for Attributes ” and particularly Section 8.3.1, “Designing Enumerated-Type Attributes” for advice on handling such attribute specifications.

All of these discussions, expectations, models, and rationales must be carefully documented, and the appropriate element and component forms filled in.

In a few cases, a single logical component may seem to live a double life as both an IU and a data-level component. For example, often there is a need for both large graphics that appear as standalone units and small graphics that appear inside sentences. If you determine that they have the same markup model and should logically be represented with the same element, it may be the case that differing contexts will enable processing applications to tell them apart; a graphic inside a paragraph, for example, might be interpreted as an “inline” graphic. If context isn't sufficient, for example, if you have “complex” paragraphs that are allowed to contain graphic IUs as well as data-level graphics, you will need to create two elements in order to give authors control over distinguishing one from the other.

It's even tricker to handle the case of single elements that have characteristics of both IUs and data-level components. The content of a footnote clearly counts as an information unit, but a reference to a footnote is a data-level component because it must be attached to a particular place in the prose. If the design team chooses to handle both the call for a footnote and the content of the footnote in the same element, it becomes difficult to figure out whether the footnote structure is an IU or a data-level component. For purposes of proceeding with the modeling work, luckily the difference doesn't matter too much until step 8, where we'll make specific suggestions for solving this problem. (Note that linking components are covered in step 9.)

5.2.5. Step 8: Populating the Branches

The design team will have done a tremendous amount of work at this point. The conclusion of step 7 might be a good time to take a break and reconvene later with renewed energy, because step 8 will require the team members to change mental gears.

If you look at all your tree diagrams, there should be “unspecified text” clouds all over the place. The goal of this step is to replace each text cloud with a model: the collection of elements and/or character data allowed freely in this context (represented by an oval with either an asterisk or a plus sign on it). Each tree branch can be thought of as a unique context, and for each context the content model must be defined. We call this matching of contexts and contents “populating the branches.

This step is particularly important because it allows the team to build an interface between the major layers of the markup model for the document type. It is a long and tedious task that benefits from a matrix approach, which ensures that no context or content model will be left out. The general structure of the matrix you will be filling in looks like Figure 5.9, “Context Population Matrix”.

Figure 5.9. Context Population Matrix

Context Population Matrix

The form that records more detailed information about each element collection is shown in Figure 5.10, “Element Collection Form”.

Figure 5.10. Element Collection Form

Element Collection Form

Following is the procedure for populating branches:

  1. Gather the classified lists of IU elements and data-level elements.

  2. Build two context population matrices, one intended for contexts that have IU contents and one for contexts that have data-level contents. Start building the first matrix by listing the classified IUs along the vertical axis. Start building the second by listing the classified data-level elements along the vertical axis, along with listing “character data.” In the matrices, list each class as a major row, with minor rows beneath it showing the individual elements.

  3. Go through the branches of all the trees you have built and find out what general content is possible in each context. There will be three possibilities:

    • A high-level collection containing IUs

    • A low-level collection containing character data and (potentially) data-level elements

    • A mixed collection containing both

    For example, the data-level matrix might look as follows at this stage:

    Contexts          
    Contents
    General Data:          
    trademarked term          
    recipe cross-ref          
    Key Data:          
    amount          
    Character Data          

    Create a column entry in one or both of the two tables per branch considered, labeling it with the element name or simply numbering it. For each context, go through the list of contents on the left and check which classes or individual elements are allowed in that context, making sure to record the reasons why you chose the way you did. Link the tree diagram location and the matrix column by replacing the cloud at the end of each tree branch by an oval representing an element collection, and numbering or labeling the oval according to its corresponding column in the relevant table.

  4. Look for recurrent patterns as you work through the tree diagrams. You will probably start noticing that the same contents are appearing in several different contexts represented by different numbers in column headings. If the various contexts with the same contents have the same rationale, group them under a column with a single descriptive name, which can either reflect the common denominator of the contexts where the contents are allowed (for example, “basic division mixture” or “title contents”) or, if the contexts are too diverse, the nature of the collection (for example, “just paragraphs”).

    Wherever the rationales differ, even if the content model is the same, do not collapse the collections into one by giving them the same context name. Your team or other designers may later decide to alter a content model in a specific set of contexts independently of the others.

  5. Go back to the tree branches and name the relevant portions of the content model with the name of the collection. Decide whether some content is required to appear in that context or not. If content is required, mark the collection oval with a plus sign ( + ); if not, mark it with an asterisk ( * ).

    Note

    Collections that contain character data can't be guaranteed to have content in them; parsers allow elements to contain zero or more characters in order to satisfy the content model. You can use a plus sign on such collections, but be aware that extra-SGML validators would be needed to actually check that there is content.

  6. Complete an element collection form for each unique collection, filling in the contents, the contexts where it is referenced, and the rationale for the choice of contents.

Filling in the branches becomes faster and faster as more and more contexts accept already defined collections. This fact does not preclude some contexts from being unique, in which case you can give them a name descriptive of their uniqueness, if feasible, or you can simply keep the context number written in the column headings of the context tables.

The following table shows an example of how the CookThis project's context population matrix for data-level elements might look halfway through the process of identifying and filling in “unspecified text” branches. This is a very simple markup model, but still some patterns are starting to emerge. (See Section C.2.3, “Information Pool Module” for an example of a complete set of context population matrices, constructed from an existing DTD.)

Contexts title editor para trademark amount
Contents
General Data: X   X X (minus self)  
trademarked term          
recipe cross-ref          
Key Data: X   X    
amount          
Character Data X X X X X

When each context has been considered, its content model described, and the rationale for the design written, it is necessary to review the element forms to complete the tree diagrams (replace all the little clouds with collection names) and the rationales and to fill in the “Is contained in” field. For some elements, filling in this field will require so many items that it saves time just to list the names collections in which they appear.

Following are a few words of advice.

  • Don't Forget Processing Expectations

    You usually can't explicitly control the amount of content supplied where collections are allowed. For example, it isn't practical to use markup models to require that abstracts contain “some number of paragraphs and lists, but no more than five elements total.” And, of course, it's impossible to use SGML to specify that the abstract “should fit on a single page.” However, if you have a specific amount of material in mind for each context, you should describe it, so that application developers can take it into account and possibly even develop additional validating software.

    A typical expectation for data-level elements is that they contain “word”-sized, “phrase”-sized, or “paragraph”-sized data; usually the word-sized elements have tightly restricted contents. You could make use of this distinction in naming your data-level element collections.

  • Beware of Self-Containing Elements

    Some IU-related elements might themselves contain IU elements directly or indirectly (for example, list items containing nested lists), and some data-level elements might contain data-level elements directly (for example, a quotation that can contain trademarked terms). As a result, you might end up with the same element on both axes, one being the context, the other one being the content. This amounts to asking whether or not this element should be allowed to appear inside itself. If the answer is “no” but otherwise the collection (including the rejected element) is used in several other contexts, then the rejected element should be excluded from the collection as a special case.

    Note to DTD Implementors

    Special exclusions such as these usually translate to an SGML exclusion from the content model, as described in Section 9.3, “Managing Parameter Entities for Element Collections”.

  • Keep “Content” and “Context” Issues Distinct

    In some cases, a single element can contain IU elements, but appear in data-level contexts. For example, you may have modeled a single footnote element both as a container for the footnote content and as the placeholder for the footnote reference at the end of the word or phrase of interest. In this case, the footnote might contain IUs, which means it will have its own column in the IU context population matrix, but it will also be available as one of the data-level elements, which means it will have its own row in the data-level context population matrix.

  • Create Relatively Generous Collections

    Use whole element classes as building blocks as much as is practical. Authoring, processing, and DTD maintenance will be simplified all around if you can check off whole element classes rather than individual elements, and the nature of classes will tend to support such decisions.

    Also, don't be too miserly with the contents of each collection. Authors find it annoying to discover that common elements have been disallowed in certain rare contexts. Typically, the simpler contexts will contain most of the structural elements but will leave out most content-based ones. Don't exclude too many structural elements without good cause.

    Of course, you will need to balance these suggestions against the benefits of having a content model tight enough to provide proper validation and good support in SGML-aware authoring environments.

5.2.6. Step 9: Making Connections

By now, your list of remaining components should be much smaller. What should remain are the components that are exclusively related to making connections, that is, revealing or recording relationships between pieces of information and between an SGML document and the “outside world.

5.2.6.1. Links

Link components are components that record the relationship of two or more pieces of information. Figure 5.11, “Identifying Links” represents the addition of links to the model.

Figure 5.11. Identifying Links

Identifying Links

There are different types of links, and the recent swell of interest in hypertext and hyperlinking has produced a variety of typologies. For argument's sake we present a simple link classification scheme here, but you do not have to adhere to this particular scheme as long as your own classification process is sufficient for your purposes.

There are two main types of links that the design team will need to address:

  • Links that serve as instructions for content to be pulled into the document at a certain location when the document is assembled or delivered, even though the content resides elsewhere. These “include-by-reference” links are often referred to as anchor points, and they are used for pulling in, for example, illustrations and multimedia sequences; entity references of all kinds also fall into this class of links. Links such as these can be said to be relatively presentational or procedural.

  • Links that connect two or more pieces of information, whether inside the same document or not, because of the inherent relatedness of their subject matter. Their purpose is to draw the attention of the readers and to suggest that they follow the link by some means (turning pages, clicking on an icon, or whatever) to browse through further related information. Textual cross-references fall into this class of links. Links such as these can be said to be relatively structural or content based.

Some content-based links can be automated simply because of the presence of the source and target(s), like links between commands appearing in a technical manual and their corresponding reference modules, or links between terms used in a document and their corresponding glossary entries. It is possible to automate links when some sort of directory exists (or can be generated) that maps all the possible source and target points, or when either of them is generated from the other one (like tables of contents and indexes).

Other links have to be hand crafted, which means that the author has to define the source, the target(s), and possibly the type or nature of the link.

In both cases, the design team seldom knows how to design the precise markup for the the links, because of the sophistication needed to architect them correctly and because of the changing state of the art. Consequently, the choice of markup for the linking devices is the sole responsibility of the DTD implementor. But to help this person in the task, the design team must provide a sufficient description of each relationship they want the markup to encode, by doing the following:

  • List all the necessary link components with all their potential source points (contexts where the source point can occur) and their potential targets. For example, for anchor-point links, the targets might include graphics, sound or video clips, footnote, and so on. For cross-reference links, the targets might include specific points in the prose, sections, illustrations, other documents, content within those documents, and so on.

  • Note the direction(s) of each link and its type and list the possible values.

  • Define which elements need to be systematically identified so as to become potential link targets. For example, each element that can be linked to probably needs to have an ID attribute. In fact, it's common to put optional ID attributes on most or all elements in the entire markup model, so that arbitrary elements can become link targets for management and/or presentation purposes.

  • Describe how the links will be used and for what purpose. For example, a link might be used to help paper navigation through the generation of page number cross-references, or to help online navigation through the creation of a hotspot that can be clicked on, or to launch the appropriate multimedia viewer to run a video clip.

  • Fully describe the processing expectations. Must the links be hand-crafted, or will they be automatically generated? What text should be generated in place for cross-references? What new pieces of the document might be generated for the presentation instances? For example, you may want to explain that the table of contents will be generated from the headings in the document, and that each item of the table must be linked to the relevant section. Also, specify what character strings or icons the application must generate according to each type of cross-reference, the language, and the media.

  • Describe any constraints. For example, if your documents will be delivered on the World Wide Web, you should list this as a constraint and require the links to be compatible with or transformable to the HTML linking technique and the URL identification technique.

With all the relevant information on links available from the design team, the implementor will be able to build a link architecture that is adapted to the project needs and constraints. The implementor may want to use a simple ID/IDREF method (discussed in Section 8.3.2, “Designing ID and ID Reference Attributes”), HyTime constructs and techniques such as architectural forms and linking indirection, or other methods. As long as the linking techniques can be implemented on an existing computer system and are sufficiently supported in the chosen authoring environment, then the actual implementations of the links in the markup model will be irrelevant to the authors and users of the documents.

There is one obvious opportunity for linking in the CookThis project: recipe cross-references. The team has specified that this component must link to a recipe, with the expectations that the name of the target recipe will be generated in place and that, in a hypertext environment, the name will be a hotspot that can lead the reader to the actual recipe. This requires that all recipes be able to be uniquely identified with ID attributes, so that they can serve as link targets.

There are also other linking opportunities in CookThis. For example, trademarked terms might serve as anchor points for trademark attributions, so that the attributions can be assembled automatically into documents that mention the terms and can be made available to hypertext users who come across the terms. (The motivation for this link may be more for legal protection than for publishing quality!) Also, if cookbooks are expected to have paper indexes, there may need to be markup for the construction of “index hits” that can be extracted and sorted, forming links back to their original locations.

The task of building links is over when all the accepted linking components have been fully specified and their rationales and constraints documented.

5.2.6.2. Special Features

The motley list of remaining components are the ones that present tricky modeling issues; they constitute the “special features.” Each special feature must be described thoroughly, and should be accompanied by a rationale for its usage and a list of circumstances in which it is to be used. The task of the design team is only to define the special features as best as they can, because the ways to implement special features are numerous and complex and should be left under the responsibility of the DTD implementor.

One kind of special feature is related to presentational issues and other downstream processing needs, and thus it usually runs counter to the SGML philosophy of purity in declarative markup. These might include presentational controls that were part of the existing stylesheet or available on the previous word processor, without which the authors and production specialists cannot achieve the proper quality of publishing. For example, there might be a component for controlling the depth to which hypertext documents will be split into individually accessible topics, or a component for controlling page breaks when the printed version is going through a copyfitting process.

Another kind of special feature is not presentational at base, though the obvious modeling solutions may seem to be presentational. For example, components for revision bars in margins, redlining, the switching of character sets for multiple-language publishing, effectivity control, and so on can be interpreted as presentational, but they can also be interpreted more abstractly—as revised regions, regions written in a certain language, or regions that apply only to one product configuration. The team should make its best attempt to interpret these features as content-based and to describe the processing expectations.

Note to DTD Implementors

Depending on the circumstances, any of the following might be appropriate for special features, and the answers might be different for reference DTDs and authoring DTDs:

  • Attributes on existing elements

    For example, elements could have language and locale attributes that indicate to processing applications that special character sets, spell checking, and so on are necessary. Or, there could be global effectivity attributes to indicate the “flavor” of presentation instance in which the element content should appear.

  • Pairs of “asynchronous” elements that are empty but associated by their mutual processing expectations

    For example, simple redlining and revision bars can be achieved with appropriate “beginning of region” and “end of region” elements. Note, however, that sophisticated information management can be hindered by this approach, and it can even defeat some of the advantages of using an SGML-aware editor.

  • SGML marked sections

    For example, information that applies exclusively to one product variant can be stored in marked sections that are controlled by IGNORE and INCLUDE status keywords stored in parameter entities.

  • SGML processing instructions

    For example, copyfitting instructions are appropriately stored in processing instructions, which can be ignored by the processing applications of interchange partners.

5.2.6.3. Entities

Finally, the design team needs to let the DTD implementor know what reusable strings and special characters need to be available to authors.

If some names, phrases, or acronyms are regularly used by authors and are likely to change globally, it will be cost and time effective to replace them with an entity whose equivalent can be modified at will and at little cost. Also, authors probably won't be able to use a keyboard alone to enter all the desired symbols and characters needed. For example, to get certain accented characters and symbols such as arrows (⇒), authors may need to use a reference to an entity instead of just typing some sequence of keyboard keys.

Appendix D, ISO Character Entity Sets describes the character entity sets defined by the ISO 8879 standard, and Section 8.7.2, “Defining Entities for Special Symbols and Characters” explains to DTD implementors how to use them.

5.2.7. Step 10: Validating and Reviewing the Design

Before disbanding, the design team needs to go through a final effort to review the specifications and make them as faultless as possible. This inspection includes going through the body of work that has been produced and doing the following:

  • Tying up loose ends

    In the final stage of such an intense effort, it's not uncommon to find many small errors: forgotten components, unfilled fields in forms, tree tree branches with clouds instead of element collection names, and so on. All the overlooked details must be fixed at this stage.

  • Checking the component lists against the component forms

    Not only should the “yes” and “no” decisions match, but a rationale should exist for every decision, particularly rejection decisions.

  • Checking the consistency of the explanatory text

    Often, terms and concepts are refined over time, and the terms are not used for the same underlying concept at the beginning and at the end of the work, and the text should be made consistent. The graphics should also be compared against the text.

  • Checking that the glossary is complete

    The glossary should include all the necessary terms (including terms that will be unfamiliar to readers of the specifications, terms used with a special meaning, and names created by the team), and the terms' definitions should be understandable by nonspecialists.

Before the document analysis report summarizing the specifications can be written, the specifications must be validated by external reviewers. Although the team members may feel that they are running out of time, it is crucially important to have potential users give their opinions on the design of the future model.

If reviewers are unhappy with the design specifications, they must respond with comments saying why, offering convincing arguments and/or examples, and indicating what, in their opinion, would consistute a more appropriate design.

If future users are not very motivated to carry out this task, the facilitator must help them review the design by presenting its conclusion in one or more live sessions with the reviewers. The recordist can write down all the remarks and critiques that are made, and summarize them in a review report.

Once the review report or the individual comments are delivered, the design team needs to meet to study them and change the model in response as they see fit. For each change, the rationale should be recorded and an entry made in the “Creation/change history” field.

The design team work is now over for a while. The facilitator and the recordist are then in charge of producing the document analysis report.

5.3. Producing the Document Analysis Report

Once the team has finished specifying the document type design and gotten its interim work reviewed, the final document analysis report must also be be written and reviewed. We've already described the contents of a typical document analysis report in Example 4.1, “Contents of a Typical Document Analysis Report”.

You shouldn't plan just to assemble the component and element forms and be done with it; the need for a single document presents an opportunity to synthesize the results properly. Also, if review comments result in design changes, make sure to record the rationales for the changes just as you've done all along.

5.4. Updating the Model

Once the DTD has been implemented, tested, and corrected (as described in Chapter 11, Validation and Testing), it is ready for use. However, as soon as it starts being used, it faces its true test: being used in a real environment by people who must get their work done, or else. You will almost certainly hear many new complaints about DTD problems at this point. Therefore, you should be prepared with a DTD maintenance program and the proper resources to carry it out.

Most problems directly related to the DTD will require analysis and design efforts similar to those performed in steps 1 through 10. Thus, you'll need to assemble a change control board that functions a little bit like the original design team. The board will need to review DTD-related bug reports and enhancement requests on a regular basis and request appropriate DTD changes. Keeping a change control board active and having a DTD implementor ready to do the requested work helps to guarantee the longevity, coherence, and quality of the DTD.

Ideally, a change control board should be composed of some of the members of the porject team, who know the DTD inside and out and remember parts of the rationales for decisions, plus a few newcomers. In reality, though, this composition is unrealistic. Members of the initial project team often scatter once the DTD has been validated. Also, as it is less exciting to maintain an existing system than to build a new one, few people clamor for the opportunity to run a maintenance program or be on a change control board. As a compromise, the members of the board should at least have the same profile as the original team members and should be current active users of the DTD. The board can be smaller than the original team; three or four people will suffice.

The maintenance work consists of the following:

  • Receiving and filing the bug reports and enhancement requests

  • Compiling them for presentation to the change control board and communicating with the senders to let them know what is happening

  • Gathering the board and presenting the issues

  • Answering each sender of a report to tell them what the board's decision was

  • Updating the DTD according to the board's requests

  • Documenting the changes and the reasons for them

  • Updating the document analysis report, technical report, and maintenance documentation

  • Updating the user documentation

  • Distributing the new DTD with an accompanying release bulletin that explains the changes and their reasons

  • Organizing additional training if the updates are significant

These tasks are usually a prelude to the tasks of updating all the variant DTDs, modifying the processing applications and aspects of the work environment that are based on the DTD, and possibly transforming existing SGML documents to make them conform to the updated DTD.

The following practices will help to make your DTD a long-term success.

  • Define and Apply a Rigorous Reporting Procedure

    Section 11.1, “Setting Up and Managing a Bug-Reporting System” describes some how to define a problem reporting procedure that can help you keep track of all comments efficiently.

  • Encourage Feedback

    Make sure all users know that you will respond to all complaints and suggestions, as long as the users follow the reporting procedure, and make sure they know what that procedure is. This message has three positive effects:

    • It makes users formalize what they are unhappy about, so that groundless complaints can be avoided and the rest are easier to understand.

    • It greatly decreases the anxiety level of users.

    • It makes users actually follow the reporting procedure.

  • Follow a Stable and Sane Update Policy

    If at all possible, keep the DTD stable for long periods of time, so that users don't have to keep retraining and you don't have to keep updating all the associated applications and documents. Backwards-incompatible changes (changes that require some transformation of existing documents) are more rare than changes that merely add optional extras to the model, so these major updates may be able to be done only once a year, once any major bugs have been shaken out.

  • Take Maintenance Seriously

    Often, the proper resources for DTD maintenance are never assigned. But even in cases where they are, sometimes the people assigned to do the work are given subtle messages that the “important work” lies elsewhere. The best way to address this problem is to ensure that the job performance of the assigned people is actually measured based on criteria such as these:

    • Are reports being filed and numbered? Are actions being taken and report senders being informed? Is the bug list (a sample of which is shown in Figure 11.2, “Bug List for SGML Project”) kept up to date?

    • Is the number of problems decreasing regularly over time?

    • Have all the problems dealt with during the most recent change control board meeting beeing fixed in the DTD and documented in the appropriate places?

If you send the message that maintenance is important, the quality of your DTD will improve rapidly.



[9] We've been asked why IUs were favored with an abbreviation and data-level components were not. It's purely historical. When modeling, we tend to call the latter simply “data” for short, which will be recognized by SGML experts as a misnomer because real data (as defined in the standard) is devoid of markup.