How do organizations manage changes and updates to specialization mappings in DITA?

November 10, 2023
|By Bryan Tipper

How Do Organizations Manage Changes and Updates to Specialization Mappings in DITA? Organizations typically manage changes and updates to specialization mappings in DITA through a structured process to ensure consistency and quality in their documentation. Here’s how it’s usually done:

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

Version Control: Many organizations use version control systems to manage specialization mapping files. Version control ensures that changes are tracked, documented, and can be rolled back if needed. It also facilitates collaboration among content creators working on the same mappings.

Documentation Updates: When changes are made to specialization mappings, organizations update the associated documentation. This includes revising mapping guidelines, best practices, and instructions for content creators. Keeping documentation in sync with updated mappings is crucial for consistency.

Testing and Validation: Organizations conduct thorough testing and validation of updated mappings to ensure they align with desired results and do not introduce errors. This phase verifies that mappings work effectively in various output formats and under different scenarios.

Feedback Mechanisms: Organizations create feedback mechanisms for content creators and subject matter experts to report issues, provide feedback, and suggest improvements. This continuous feedback loop helps fine-tune specialization mappings over time.

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

Example:

Consider a scenario where a DITA specialization introduces a non-standard element <chemical-reaction> to describe chemical reactions in a chemistry documentation project. Mapping guidelines for this non-standard element must be 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>