Eric Severson
Flatirons Solutions

“Power corrupts, and absolute power corrupts absolutely.” It was true when Lord Acton said it in 1887, and we all know examples of how it applies today. But have you ever thought about this idea in the context of an XML publishing system?

Like its political counterparts, dictatorial XML often starts out with the best of intentions. Usually this takes the form of a sincere attempt to precisely identify all the underlying information elements and to rigorously describe the relationships among them. This maximizes XML’s ability to control and describe structure and is seen as a way to promote the usefulness of the information for the future.

However, experience shows that the needs of the future can’t really be anticipated at that level of detail. And getting too carried away with structure can cause a lot of pain in the present. Over-engineering the XML creates an inflexible and overly constrained environment for authors, making it difficult for them to adjust content as documents evolve. When this happens, authors are likely to resist—and may even reject—the new system.

Of course, that’s not to say that structure is bad. Nobody likes a dictator, but there really are some things that need to be consistent, some rules that really do need to be followed. And an appropriate amount of tagging in the content actually will make it easier to transform and transition in the future.

The secret is knowing how to achieve the right balance between precision and flexibility. Erring in either direction can create nightmares of different kinds.

In our Content Architecture work, we’ve discovered that this balance can rarely be achieved in the same way for all publications or for all kinds of material. How rigorous or deep you go depends on the context you’re in. However, there’s a simple rule of thumb that we’ve found very useful.

When looking at a document, think of it as being composed of two kinds of information:
Core material that forms the heart of the documentation (e.g., product descriptions, part specifications, feature lists, and so on…).
Introductory and supplementary material that forms the “packaging” around the core material.

Core material is typically repeated and needs to have consistent structure across all instances. For example, a product description in a catalog might always include a product name, followed by an overview, followed by a benefits list, followed by a price. There may be hundreds of products in the catalog, and you want all the descriptions to follow exactly this format. This is a great use of the rigor and precision that XML can bring.

But what about the introductory section of the catalog that describes the company and its offerings? Or the overview section of a technical manual? While this material may have a lot of internal structure—expressed as detailed headings and sub-headings—that doesn’t mean that all of this should be modeled explicitly in XML. Instead, it might be smarter to leave this as “generic” sets of headings, paragraphs, and lists. Why? Because authors may decide there’s a better way to write this material, a better way to structure it to get the message across. And you don’t want to have to make official changes to the DTD (XML Document Type Definition) every time an author decides to do so. Changing the DTD can be a cumbersome process that can also have a widespread effect on many parts of the system. Introductory and supplementary information doesn’t repeat, doesn’t need to be perfectly consistent, and sections will be added and deleted. Unlike the core material, youwant the authors to be able to freely make structural changes as they see fit.

To summarize, then, here’s our advice:
Use the power of XML, but don’t be too absolute. Think of designing XML content as achieving the right balance between precision and flexibility.
Resist the temptation to invent an explicit tag name for every section in the document or to model every current relationship explicitly in the DTD.
Think of a document as a repeating set of core elements, surrounded by more generic introductory and supplementary material.
Use specific structure for the core elements, ensuring their consistency and completeness.
Use generic structure for the introductory and supplementary material, ensuring that the DTD doesn’t have to be changed every time the author wants to tweak the organization of the text.

Flatirons Solutions specializes in content management and XML-based publishing and is located in Boulder, Colorado. Eric can be contacted, or at (303) 544-0514 x25.