Are there best practices for managing author comments in DITA outputs?

November 10, 2023
|By Bryan Tipper

Managing author comments in DITA outputs is essential for maintaining content clarity and streamlining the review and editing process.

Author comments in DITA are annotations or notes made by content creators, reviewers, or editors within the document. They are used to provide context, suggestions, or explanations regarding the content. Managing author comments effectively ensures that they are accessible, actionable, and do not disrupt the flow of the content.

Some best practices for managing author comments in DITA include visibility, consistency, positioning, actionable feedback, use of markup, and review workflow.

Visibility:

Author comments should be clearly distinguishable from the main content. Styling elements such as color, font, or background can be used to make them stand out.

Consistency:

Maintain a consistent style for author comments across the document to make them easily recognizable.

Positioning:

Author comments can be placed in the margin or in callout boxes to avoid cluttering the content.

Actionable Feedback:

Ensure that author comments provide constructive feedback or explanations. Vague or ambiguous comments may hinder the content development process.

Use of Markup:

Consider using XML-based markup or tags to define author comments, making it easier to identify and process them during production.

Review Workflow:

Implement a structured workflow for addressing author comments, including resolution, verification, and tracking.

Example:

In a software user manual created using DITA, an author comment is used for clarification regarding a specific feature. It is managed according to best practices.



<!-- Author Comment -->
<note type="author-comment">
  <title>Author Comment</title>
  <body>
    This section may need further elaboration regarding the user interface changes in version 2.0.
  </body>
</note>

In this example:

Visibility: The comment is styled differently to distinguish it from the main content, with a distinct note type.

Consistency: All author comments in the manual are formatted similarly.

Positioning: Author comments are placed in a callout box, ensuring they do not disrupt the primary content.

Actionable Feedback: The comment provides clear guidance for improving the content.

Use of Markup: XML tags, such as <note>, are used to define the comment type.

Review Workflow: A documented process is in place to address and resolve author comments.