Friday, September 15, 2017

Small problems with the DITA standard

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Don't get me wrong, I think that DITA is a great standard for writing technical documentation, it has lots of reuse and linking potential and it's in general well thought and comprehensive.

Over the years various of our Oxygen XML Editor clients or me personally have encountered various limitations/quirks in the DITA standard that I wanted to share below. These complaints are not related at all to the publishing part and I think that some of them will probably be resolved as the DITA standard evolves from one version to another. Also probably a good part of these issues could not be effectively fixed because the DITA standard has strived (and succeeded) to be backward compatible. So here we go:
  • When I create a DITA specialization in order to add a new attribute according to the specification I need to add that attribute to all DITA elements. I think the main idea was that the new attribute is a profiling attribute so it makes sense to be added to all elements but sometimes, just sometimes you would need to funnel this behavior and make the attribute available only on a certain element and still consider the specialization as a valid DITA specialization.
  • The existing xml:lang attribute cannot be used to profile and filter out content. In the past we had users somehow mixing languages in the same DITA Map and expecting to output either for one language or the other by filtering out based on the xml:lang attribute.
  • You cannot easily profile/filter out an entire column from a CALS table. For example you cannot add a profiling attribute directly to the DITA colspec element in order to remove entire table columns when publishing. So the alternative is to use a DITA simpletable and define the profiling attribute on each of the cells in the column or to perform some kind of output customization based on a magic outputclass attribute set on a certain element in the table.
  • There are too many constraints imposed when writing DITA Specializations. Robert Anderson, the DITA OT project manager and OASIS member involved in defining the DITA standard had two interesting blog posts on this:
  • With most of the material being published for web and with the need to dynamic include media resources (video, audio) in the published HTML content it's a pity that the DITA standard does not yet have specialized <audio> and <video> elements. Again we need to rely on the magic outputclass attribute to give semantic to the too generic DITA <object> element.
  • Sometimes there are two or more ways of doing something. For example choosing between using a CALS table or a simple table or choosing between using conkeyref, keyref or conref to reuse small pieces of text. Why have the <simpletable> at all in the DITA standard as long as a CALS table without any cells spanning is simple enough? The LightWeight DITA Project is an alternative to DITA which tries to simplify the standard and eliminate such problems: http://dita.xml.org/blog/lightweight-dita.
  • DITA elements which have conrefs or conkeyrefs need to also have the required content specified in them. So I cannot simply do this:
    <table conref="path/to/target.dita#topicID/elementID"/>
    and instead I need to do this:
    <table conref="path/to/target.dita#topicID/elementID">
      <tgroup cols="1">
       <tbody>
         <row>
           <entry/>
         </row>
      </tbody>
     </tgroup>
    </table>
    and have all the required table elements and tgroup elements plus required attributes filled out even if the expanded conref will replace the entire original element.
  • You cannot refer using a key directly to a subtopic element. If the standard would allow a DITA Map to refer directly to a subtopic element like this:
    <keydef href="topics/reusableComponents.dita#topicID/tableID" keys="reused_table"/>
    you could reuse the table without needing to specify the ID to the reused element on each conkeyref:
    <table conkeyref="reused_table"/>
  • Some DITA elements (eg: <li>, <entry>, <section>) have a very relaxed content model in the specification allowing both text and block elements, in any order. So when using visual editing tools this leads technical writers create DITA content looking like this:
        <li>
            Preview:
            <p>Here are some of the preview</p>
        </li>
    as the visual editing tool cannot by default impose an editing constraint if the standard does not. Usually for such cases additional Schematron checks can be handy.
  • The DITA content is not automatically profiled based on the new DITA 1.3 deliveryTarget attribute. So setting deliveryTarget="pdf" on a DITA element will not automatically filter it out of the HTML based outputs, the attribute is treated just like another profiling attribute and it can be filtered out from the DITAVAL file.

This concludes my complaint list. Anything else you encountered in the DITA standard which bothers you?