Conditionals vs. Composition

This entry is part 5 of 7 in the series DITA

This article is part of a series that describes the 20-some decisions that face every DITA project. The goal is to identify the pros and cons for each decision and, where warranted, record the known “best practices” around each decision point. (Most of them can be covered in a single article. But a couple, like this one, are intricate enough to require an article of their own.) The series concludes by considering whether DITA would benefit from the creation of a specialization for a “
Decision Guide“.

Read more

Transcluding the Invariants

This entry is part 6 of 7 in the series DITA

Having settled on a strategy of composition, the next question is whether to transclude the parts of the text that change from version to version (the variants) or whether to transclude the invariants, instead—the boilerplate and other things that don’t change. This article lists the advantages of the latter course of action.

Read more

Decision Guide Specialization

This entry is part 7 of 7 in the series DITA

Figuring out which components you need and accessing the documents that describe them is a big issue for any reasonably complex system. Providing an end-user with the ability to do that is a huge part of “usability” in documentation. One of DITA’s most important advantages is the ability to define specialized document structures. That capability can be used to define a Decision Guide document type.

Read more