Comments

Adding comments to pages and references is a useful way to record additional details, and collaborate with team members.

Why Use Comments?

Comments help you discuss changes with teammates, capture decisions, and leave notes for later. Teammates you tag can be notified automatically, so review conversations stay attached to the relevant content.

Comments on Pages

On documentation pages, comments are added directly on the text and anchored to the selected content.

Add a Comment on a Page

1. Highlight the text you want to comment on.
2. Select Comment in the toolbar.
3. Type your comment.

Your comment will appear on the right-hand side of the page, aligned with the text you commented on.

View and Navigate Comments on a Page

• Comments display in a right-hand column next to the page content.
• Because comments use the right side of the layout, the table of contents may be hidden while comments are visible.

View Options

Use View options in the right sidebar to control what you see:

• Show table of contents: shows the table of contents even when comments are visible.
• Show resolved comments: toggles whether resolved comments are shown.
• The current watch state for the page is also available here.

Comments in API References

API references continue to support comments associated with specific parts of the reference. When you highlight text and write a comment, the comment is associated with that exact part of the API reference. Comments can be associated to:

• API reference description
• Authentication schemes
• Servers
• Tags
• Operations
• Operation requests
• Fields in operation requests
• Operation responses
• Fields in operation responses

When a teammate clicks on a comment, the associated part will be highlighted.

Tagging Teammates

To tag your teammates in a comment, start by typing an @ character. A list of all teammates will be available to choose from.

Resolve Comments

Once you are done with a comment, you may resolve it to hide its details. Resolving a comment would notify the watchers of the resolution status.

Publishers and admins can resolve all comments at once.

You may setup Ask before Publishing if you wish to only publish if all comments are resolved.

Watch/Mute

Once you comment on a page, or get tagged in one, you become a watcher of that page. Being a watcher means being subscribed to all comment activity that happens on the page.

When you are a watcher, you will be receiving e-mails summarising the changes that happened in the page comments.

To unwatch a page at any time:

• Open View options in the right sidebar.
• Toggle Notify to set it into Muted.

To resubscribe, toggle Notify into On all comments.

You may also unsubscribe from all activity notifications from the User Settings.