Atlassian Confluence is a powerful collaboration and documentation tool that enables teams to create, organize, and discuss content. An important feature of Confluence is the ability to annotate and comment on documents directly within the platform.
As a technical writer with over 5 years of experience using Confluence to create documentation, I will provide a comprehensive guide on best practices for annotating and commenting in Confluence.
Table of Contents
Benefits of Annotating and Commenting
Annotating and commenting in Confluence delivers several key benefits:
- Enables feedback loops – Subject matter experts, reviewers, and other stakeholders can provide feedback by adding annotations and comments directly on the document. This kicks off iterative feedback loops to improve the accuracy and quality of the documentation.
- Centralizes documentation reviews – Rather than managing feedback in separate documents like Word or emails, everything stays together in the Confluence document. This provides full visibility and context.
- Creates an audit trail – Every annotation and comment is tracked with the author and timestamp. You can see the entire trail of changes made to refine the document over time.
- Facilitates remote collaboration – Since Confluence is cloud-based, distributed teams can collaboratively review and provide feedback on documentation from anywhere.
Types of Annotations
There are three main types of annotations you can add in Confluence:
Highlights
Highlighting text is a simple way to emphasize important passages or flag issues. The highlight color can be customized to indicate different types of feedback. For example, yellow highlights may indicate follow-up items while blue highlights identify inaccurate content.
Comments
Comments enable you to leave freeform feedback tied to a specific section of text. They are useful for raising questions or considerations about the documentation.
Resolves
The “resolves” annotation lets you directly link a comment to the next version of the document where the feedback was addressed. This creates an audit trail showing how each comment was resolved.
Best Practices
Follow these best practices when adding annotations and comments in Confluence documents:
Use Different Highlight Colors
Use color coding to categorize types of feedback:
- Yellow = Follow-up item
- Blue = Inaccuracy
- Red = Critical issue
Leave Constructive Comments
Frame comments constructively to kick off a thoughtful dialogue. Ask clarifying questions rather than making demands.
Reply to Comments
Reply directly to comment threads to keep related discussion organized under each initial comment, avoiding clutter.
Resolve Comments
Mark comments as “resolved” once addressed in the next version. This creates a record showing how each comment was handled.
Tag Users
Tag people using @mentions to notify them of open action items or direct questions.
Limit Access
Restrict view and edit permissions if documentation contains sensitive information.
Replying to Comments
Replying directly to a comment keeps related discussion organized under the initial comment, avoiding clutter:
- Hover over the comment and click Reply: Reply to comment
- The reply field opens – enter your comment and click Save: Enter comment reply
- The reply appears nested under the initial comment: View reply
This keeps related discussion organized under each initial comment, avoiding clutter.
Resolving Comments
Mark comments as “resolved” once addressed in an updated document version:
- Hover over the comment and click the Resolve icon: Resolve comment
- In theResolve field, add a comment summarizing how it was addressed and click Resolve: Enter resolve details
- The comment is now marked as resolved, keeping an audit trail: View resolved comment
Marking comments as resolved maintains an audit trail showing how each was addressed to improve the documentation.
Summary
Annotating and commenting helps create collaborative feedback loops to improve the quality of Confluence documentation. Following these best practices will lead to constructive reviews:
- Use different highlight colors to categorize feedback
- Leave constructive comments and questions
- Reply directly to comment threads
- Mark comments as resolved once addressed
- @mention users to assign action items
Mastering annotations and comments unlocks the full power of Confluence for centralized documentation review and collaboration.
As a technical writer with years of experience using Confluence, please let me know if you have any other questions!
