What challenges can arise when coordinating the efforts of technical illustrators and IT writers in DITA projects?

November 10, 2023
|By Bryan Tipper

Coordinating the efforts of technical illustrators and IT writers in DITA projects can present several challenges. While DITA offers a structured approach to content creation, it requires effective collaboration between these two distinct roles to produce cohesive and comprehensive IT documentation.

Content Synchronization

One challenge is ensuring the synchronization of textual content and visual assets. Technical writers and illustrators must work closely to align written explanations with accompanying illustrations or diagrams. A lack of coordination can lead to inconsistencies, where the text and visuals do not complement each other, potentially causing confusion for the readers. This requires clear communication and collaboration to maintain content coherence.

Version Control

Another challenge is version control, especially when visual assets undergo revisions. If a technical illustrator updates a diagram, it’s essential for both roles to be aware of these changes. The DITA project must manage versions effectively to ensure that the correct version of visual assets is used in the documentation. Misalignment in version control can result in outdated or mismatched content, impacting the quality of the documentation.

Example:

Here’s an example of how content synchronization challenges can be addressed:


<topic id="network_configuration">
  <title>Network Configuration</title>
  <body>
    <illustration href="diagram-network-architecture.dita" />
    <p>Configure your network following the diagram above...</p>
  </body>

In this example, a DITA topic integrates an illustration with textual content. Effective coordination ensures that the illustration matches the instructions provided, enhancing the quality of the documentation.