How do authors work with DITA specializations during content creation?

November 10, 2023
|By Bryan Tipper

Authors work with DITA specializations during content creation in a structured manner to maintain consistency and quality in documentation. The process involves several key steps:

Change Management Process: Organizations establish a formal change management process to handle specialization mappings. This includes documenting proposed changes, reviewing them, obtaining approvals, and tracking implementation. This ensures control and visibility over mapping updates.

Version Control: Many organizations use version control systems to manage specialization mapping files. Version control helps track changes, document them, and provides the ability to roll back if necessary. It also promotes collaboration among content creators working on the same mappings.

Documentation Updates: Whenever changes are made to specialization mappings, organizations update the associated documentation. This involves revising mapping guidelines, best practices, and instructions for content creators to maintain consistency and alignment with the updated mappings.

Testing and Validation: Thorough testing and validation of updated mappings are essential to ensure they produce the desired results and do not introduce errors. This phase verifies that mappings work effectively across various output formats and under different scenarios.

Feedback Mechanisms: Organizations establish feedback mechanisms for content creators and subject matter experts to report issues, provide feedback, and suggest improvements. This feedback loop helps refine specialization mappings over time, making them more effective.

Training and Awareness: Content creators receive training and participate in awareness programs to stay informed about mapping updates and changes. This ensures that authors understand and can effectively work with the revised mappings.

Example:

Let’s consider a scenario where a DITA specialization introduces a non-standard element, such as <chemical-reaction>, to describe chemical reactions in a chemistry documentation project. To work with this non-standard element, mapping guidelines are documented to ensure proper usage and customization of templates, stylesheets, and transformation scenarios.


<!-- Mapping non-standard DITA element for chemical reactions -->
<map>
  <topicref href="specializations/chemistry.dita">
    <map>
      <topicmeta>
        <keywords>
          <keyword>chemical reactions</keyword>
        </keywords>
      </topicmeta>
    </map>
  </topicref>
</map>

<!-- Using the non-standard element for a chemical reaction in a DITA topic -->
<topic id="chemistry-topic">
  <title>Understanding Chemical Reactions</title>
  <body>
    <chemical-reaction>
      <reactants>
        <chemical-compound>H2</chemical-compound>
        <chemical-compound>O2</chemical-compound>
      </reactants>
      <arrow>
        <label>=></label>
      </arrow>
      <products>
        <chemical-compound>H2O</chemical-compound>
      </products>
    </chemical-reaction>
  </body>
</topic>