Two impediments to authoring in DITA are domain configuration and loose content models. This document discusses loose content models. This issue is complicated enough that it made sense to partition it into a series of claims that could be discussed individually. That way, objections that better apply to another claim can be postponed and discussed within the context of that other claim.
Claim 1: The content models for the DITA common elements are too loose for authoring
A best practice for most large document-centric structured vocabularies is to subset them, removing element choices that serve no useful purpose for authors. These removed element choices are in the vocabularies because they have uses outside of authoring. However, their presence in the authoring environment leads to additional complexity, erodes the usability of the semantic vocabulary, and increases the likelihood of poor element selection.
There are ample opportunities for pruning the content models in the DITA common elements and in the technical content package. These opportunities mainly fall into one of two categories: 1) removing text and inline elements from block wrapper elements, and 2) removing block elements from within other block elements.
Claim 2: DITA needs an out of the box package where the common elements and technical content elements have been optimized for authoring
Unfortunately, most organizations that implement DITA do not have the expertise to implement the 13 or so constraints needed to subset the common elements for authoring. Task is even worse. It requires the 13 common element constraints plus another 16 constraints for task elements (see @domains in Exhibit 1 at the end of this document).
Organizations that have the resources to implement the constraints often don’t do so. Tools people often don’t understand why subsetting is necessary for authoring, so they look at the complexity of implementing constraints and decide that it isn’t worth it. Some vendors spread FUD (Fear, Uncertainty, and Doubt) about specializations, constraints, and shell configuration.
All of this means that if we want most DITA adopters to have a good authoring experience, we need to provide them a package that offers it.
Claim 3: Applying multiple DITA constraints to multiple shells is way too complicated
Ask anybody who has done it.
Claim 4: Distributing a DITA authoring package that does subsetting through DITA constraints will be mean further complexity when creating specialized topic types.
Suppose an organization wishes to create a topic specialization that implements a new information type called “principle” for writing rules and policies. The organization will undoubtedly want the same common element constraints in their specialization. Creating a specialized topic type with multiple constraints is significantly more difficult than creating a topic specialization without constraints.
Claim 5: The common elements should be refactored to optimize content models for authoring, assuming that there is a way to replace the functionality provided by the loose content models
The loose content models in the common elements served a purpose that has not gone away. Assuming that purpose can be provided by some other means, it makes sense to optimize the common element content models for authoring. Doing so will immediately get rid of the quagmire of constraints needed to optimize the common element for authoring.
Exhibit 1: Authoring task topic from the Tagsmiths Authoring plugin
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE task PUBLIC "-//Tagsmiths//DTD DITA Authoring Strict Task//EN" "authoring-task.dtd">
<task id="sampleTask" domains="
(topic task)
a(props deliveryTarget)
(topic abbrev-d)
(topic equation-d)
(topic hazard-d)
(topic hi-d)
(topic indexing-d)
(topic markup-d)
(topic mathml-d)
(topic pr-d)
(topic relmgmt-d)
(topic sw-d)
(topic svg-d)
(topic ui-d)
(topic ut-d)
(topic markup-d xml-d)
(topic simpleAbstract-c)
(topic simpleDd-c)
(topic simpleDesc-c)
(topic simpleEntry-c)
(topic simpleExample-c)
(topic simpleItemgroup-c)
(topic simpleLi-c)
(topic simpleLinkinfo-c)
(topic simpleLq-c)
(topic simpleNote-c)
(topic simpleP-c)
(topic simpleSection-c)
(topic simpleSectiondiv-c)
(topic simpleStentry-c)
(topic task simpleChdesc-c)
(topic task simpleChdeschd-c)
(topic task simpleChoice-c)
(topic task simpleChoption-c)
(topic task simpleChoptionhd-c)
(topic task simpleContext-c)
(topic task simpleInfo-c)
(topic task simplePostreq-c)
(topic task simplePrereq-c)
(topic task simpleResult-c)
(topic task simpleStepresult-c)
(topic task simpleSteps-informal-c)
(topic task simpleStepsection-c)
(topic task simpleSteptroubleshooting-c)
(topic task simpleTasktroubleshooting-c)
(topic task simpleStepxmp-c)
(topic task simpleTutorialinfo-c)
(topic task strictTaskbody-c)
">
<title>Task title</title>
<taskbody>
<prereq>
<p>Do something else first.</p>
</prereq>
<context>
<p>Only do this at the right time.</p>
</context>
<steps>
<step>
<cmd>First step</cmd>
<info>
<p>More about this step</p>
</info>
</step>
<step>
<cmd>Second step</cmd>
<steptroubleshooting><p>You messed up.</p></steptroubleshooting>
</step>
</steps>
<result>
<p>You get this.</p>
</result>
<tasktroubleshooting><p>This isn't right.</p></tasktroubleshooting>
<example>
<p>It looks like this:</p>
</example>
<postreq>
<p>Go do this other thing next.</p>
</postreq>
</taskbody>
</task>