Resources‎ > ‎Articles and Books‎ > ‎

Subsetting and customizing DITA (600+ words)

Subsetting, in the context of this document, means to remove or reorganize elements, attributes and attribute values to customize the way that options are presented, while ensuring all the DITA specifications are followed.

Why subset and modify DITA

The three main reasons to subset include changing default tags, modifying the order or elements and adjusting the frequency of element use.

The default tags in the DITA specification include close to 200 elements. In many cases, tags provide features that are not required in your documentation or provide undesired redundancy.

Modifications to the default element order allow restrictions to the organization of information. If this still adheres to the principles of the DITA specification your content remains compliant and your authors have a guided workflow.

Many of the elements in the DITA specification allow child elements to appear with no restrictions. This means that, basically, authors can insert a wide variety of elements as often as desired.

Sample subsetting of a DITA element

As a practical example of subsetting within the DITA specification, consider the step element. This element has numerous default child elements with few limitations placed upon them. By defining a subset of the step element we allow authors to create content while ensuring specific guidelines are followed.

The step contains numerous elements; some of which repeat and appear in an order that may not be repeated the next time the element step is used. By developing a custom rule additional restrictions can be enforced for consistency within your organization.

An example of a custom definition of step is seen below:

cmd, (info, choices?)? 

The step contains a required cmd element. After the cmd there is a single info and a choices element. The restriction helps to ensure consistency and provides more detailed guidance for each of the authors when working with a step.

The result of the customization is a document set that is more professional, consistent and easier to manage. Editing and translation are simplified as there are fewer decisions that need to be made based on writing style.

Subsetting tags and attributes

There are close to 200 tags in the DITA specification. One of the easiest things you can do to make a DITA implementation simpler is to reduce the number of tags.

It is important to first plan your document set and then begin to subset as the removal of high level elements and all associated child element is difficult to undo later.

Remember that many of the attributes are reused throughout the DITA specification and it may be better to remove them on an element by element basis rather than removing them from the DITA specification completely.

Drawbacks to subsetting

There are two key drawbacks to consider before subsetting: tab limitation and stricter rule requirements. If a DITA implementation is well planned neither should be a major problem in managing the way DITA is used.

While subsetting helps to implement a stricter implementation of the DITA standard, it also deviates from it. By only supporting a key set of tags you restrict the ability to import other content that complies with the DITA specification.

By redefining the order of elements and their frequency, you effectively rule out some combinations of elements that others may use. In doing so, you may be limiting the usefulness of content that others provide that match the DITA specification.

Conclusion

Subsetting the DITA specification and modifying the default rules can provide many benefits to an organization. A restricted set of elements reduces the need to develop formatting and transformation rules for all possible combinations of elements. It also allows organizations to further control the types of content used and the way that they are used. This results in far more consistent documentation.

Why Multiple Versions?

This document is available in many differnt versions, each of which expands on the ideas below. The reason: Different people want different amounts of information. So, pick the format that best suits your needs. Read about subsetting in about 4000 words, 2000 words, 1250 words, or 600 words. Keep it under 300 just by reading the rest of this box!

Subsetting means to remove or reorganize elements, attributes and attribute values to customize the way that options are presented, while ensuring all the DITA specifications are followed.

Some tags in the DITA specification may support features that are not required or provide undesired redundancy. Modifications to the default element order allow restrictions to the organization of information.

One of the easiest things you can do is to reduce the number of tags. Remember that many attributes are reused throughout DITA and it may be better to remove them on an element by element basis rather than removing them from DITA completely.

While subsetting helps to implement a stricter implementation of DITA, it also deviates from it. By only supporting a key set of tags you restrict the ability to import other content that complies with DITA. By redefining the order of elements and their frequency, you effectively rule out some combinations of elements that others may use.

Subsetting DITA and modifying the default rules can provide many benefits to an organization. A restricted set of elements reduces the need to develop formatting and transformation rules for all possible combinations of elements. It also allows organizations to further control the types of content used and the way that they are used. This results in far more consistent documentation.

Comments