The best documentation spawns from a conversation. Often the conversation starts around a user story, but tends to continue throughout product development and testing. Use comments to keep the conversation as close to your documentation as possible, so nothing is lost.
Comments can be very simple, or contain any of the rich formatting you use on a Confluence page. You can also use @mentions to bring specific team members into the conversation. When you add a comment with "@[teammembersname]", the team member receives a notification about the comment so they can participate in the conversation. Team members can reply to any comment on the page to add their thoughts and answer questions. This is a far more natural way to discuss with your team rather than emailing back and forth.
There are two different types of comments in Confluence.
At the bottom of every Confluence page there is a comments section. These page comments are handy for discussing the content on the page in a general sense and bring other teammates into the conversation. Page comments are great when you want to:
- Comment on the structure of the documentation overall and recommend any large changes
- Bring in other teammates to review or add to the documentation
- Discuss the overall content to discover how the team would like to move forward
To pinpoint a conversation to a specific piece of content on a page, you can highlight the text and add an inline comment. Inline comments stick with the content on the page—unless it's completely replaced—so your team can work together until it's been improved. Once the final piece of content is written, the inline comment should be resolved so it doesn't hang around forever. Inline comments are handy when you want to:
- Ask a question about a piece of content
- Point out a typo
- Add some additional thoughts that might be useful for the writer
- Give kudos on some well written content
Learn more about comments on pages.
To get a page in front of a team member, sometimes quickly sharing it is just the thing. Sharing is very handy in situations where you want to make a team member aware of existing documentation. This can be useful in situations like when a product manager needs to share an overview of existing product functionality with an engineer or when a support representative needs to share a solution article. Team members can share documentation so everyone can quickly understand the current functionality and make notes on what will need to be changed. Every Confluence page has a "Share" button you can use to share the page with one or more team members. When a page is shared with a team member, they get a notification.
Learn more about sharing a page.
Write Together and Get Better