by Doug Williams
DITA written correctly enables reuse. DITA not written correctly will require refactoring for reuse.
Types of DITA technical debt:
- Improper use of semantic elements. You can’t just put things in paragraph elements, or substitute context elements for short descriptions, or use cite as a way of italicizing content, or in other ways use the semantic elements, which have a purpose that is described right on the writer’s screen as they enter elements, as though they had no function other than those a writer chooses to use them for in the context of a single publication, or as a matter of personal style. Failing to use short descriptions, or using formatting elements such as PRE or I or B, or misusing other elements in the DITA set limits stylesheet control of output, and what we can do with reusing content in other contexts.
- Improper structure. You can’t write around accessibility restrictions for things such as empty table cells by putting in hyphens, or other workarounds. The violation is still there.
- Excessive use of DITA or SDL elements to produce complex content. It is possible to create enormously complex content in DITA using phrase elements and conrefs, or SDL variables, and SDL’s conditional text (ishConditions) increases the capability of creating content that is difficult to maintain in even one user document, and that is unreusable in other contexts. This was one of the issues Amber Swope cited in her review of Oracle doc content generally in 2017.
- Embedded inline links. Inline links generally present issues for users. A topic should have three links at most, because users don’t follow links from heavily hyperlined content in task-based user assistance. Two or three links of immediately relevant content are usually the limit of customer interest. Every link becomes a potential single point of failure for a build, and every link increases the difficulty of reuse.
- Inconsistent adherence to concept, task, reference and orientation (more commonly called “container”) template guidelines. Inconsistently developed content again can become very specific in look and feel to one publication, with style inconsistencies that make reuse more difficult.
The answer to this technical debt is to rewrite the content. How easily this can be done depends on the level of deviation from standard guidelines for DITA content.