Are there guidelines for involving subject matter experts (SMEs) in DITA-based IT documentation reviews?

November 10, 2023
|By Bryan Tipper

When involving subject matter experts (SMEs) in DITA-based IT documentation reviews, it is crucial to follow specific guidelines to ensure a smooth and effective collaboration process. SMEs possess in-depth knowledge about the subject matter, and their input can significantly improve the quality and accuracy of IT documentation. Here are some guidelines to consider when working with SMEs in the context of DITA XML:

1. Clear Communication:

Maintain clear and open communication with SMEs throughout the documentation review process. Clearly define the scope, objectives, and expectations of the review. Provide SMEs with access to the DITA content, review guidelines, and a timeline for their feedback submissions.

2. Use of Specialized Review Tools:

Consider using specialized DITA review tools that allow SMEs to work directly with DITA XML files. These tools enable SMEs to add comments, suggestions, or modifications within the DITA content, ensuring that their feedback is integrated seamlessly into the documentation.

3. Training and Support:

Provide training and support to SMEs who may not be familiar with DITA XML. Offer guidance on using DITA authoring and review tools to ensure that SMEs can effectively navigate and comment on the structured content.

Example:

Here is an HTML-friendly example illustrating how SME feedback can be integrated into DITA XML documentation:


<topic id="topic1" audience="reviewer">
  <title>Sample DITA Topic</title>
  <body>
    <p>This is the content of the DITA topic.</p>
    <note audience="reviewer" status="draft">
      <p>SME feedback: Suggest adding more details about the software architecture.</p>
    </note>
  </body>
</topic>

In this example, the DITA topic includes a “note” element with SME feedback marked as “draft.” This feedback is seamlessly integrated into the DITA XML, and the documentation team can review and address the comments provided by the SMEs to enhance the documentation’s quality.