Earlier in the series:

Here comes Reason #3:

Reason #3: DITA Lets You Enforce and Reuse Consistent Structure

With DITA, you can enforce consistent structure both on the level of an entire document and individual requirement. Having a unified and consistent structure across your requirements documentation which includes requirement specifications, test cases, cost estimate, and sales proposal, is critical for making sure that no important information is missing, and the documents can be easily read and understood.

Enforcing a Structure on the Level of a Document

Suppose, you need to write a sales proposal for a customer. It’s quite safe to assume that all your proposals have the same structure. For example, any proposal should include an introduction, description of scenarios to be supported, requirements, pricing information, payment terms, and legal statements.

To let you be sure that all proposals do have the same structure, it has to be enforced (not just recommended in an MS Word template) into a proposal. An obvious way to enforce a structure is to create a structural template that will be used every time when you create a new proposal.

Similarly, you can create such structural templates for other types of requirements documents, such as requirements specifications, test cases, cost estimate, and so on. In the same way as the internal structure of a DITA topic is determined by its information type, the structure of the document template is defined by the document genre. In other words, the document genre to a particular document is the same as DITA information type to a particular topic.

To define the structure of a document genre, you can use subjectScheme maps. For example, this is how a subjectScheme map for the Proposal genre might look:


So the subjectScheme map is used to define the sections of the document of a certain genre. To define how each of these sections should be populated with actual content for a particular proposal, you can build a classification map. The classification map refers to the document sections that you defined in the subjectScheme map:


As you can see, the hierarchy and order of the topics that belong to different document sections isn’t really important because the structure of the entire document is defined once in the genre definition in the subjectScheme map. So the classification map just says which topics should be included into a specific proposal, and in which document section each topic should be published.

The real strength of subjectScheme and classification maps comes with automation, when as part of the automated assembly, the proper template (that is the subjectScheme map) is picked up and filled out with relevant topics stored somewhere in the repository (based on the classification map).


Enforcing Structure into a Requirement

On a requirement level, you can also enforce structure by creating templates with a pre-defined structure or by specializing DITA (for example, you can define elements with the names that better reflect the semantics of requirements than generic names, like <p>, <ul>, or <table>) for different types of requirements.

By enforcing a structure, you make sure that all important information about the requirement is provided, and the description of all requirements follow the same pattern so that the reader can quickly understand them.

Leave a Reply

Your email address will not be published. Required fields are marked *