Comments
Adding comments to pages and references is an effective method for recording additional details and collaborating with team members. These comments appear conveniently in the Activity right sidebar, allowing for easy access and review by all members involved.
Why to use Comments?
Comments are useful for discussing issues with your teammates on a page. They also notify team members automatically. You can use comments for future notes and to record past decisions about a page.
Where to access Comments?
To see and write comments, open the Comments
How do Comments work?
To add a comment on a specific line in the documentation, highlight the line and select Comment in the toolbar, or use the keyboard shortcut. The comments input will copy the line content and ask for your further input.
To add a comment, open the Activity right sidebar and write in the Add Comment input.
Hit Add when you're done.
Who can use Comments?
All your teammates can comment. You can set up teammates who are experts but not contributors as reviewers, allowing them to read pages and write comments. See user roles..
Comments in API References
In API references, when you highlight text and add a comment, that comment is linked to that specific part of the API reference. Comments can be associated with:
- 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 corresponding section will be highlighted for better visibility and navigation.
Tagging Teammates
To tag your teammates in a comment, type the @ character. You will see a list of all teammates to choose from.
When you tag someone in comments, both you and the tagged individual will be designated as watchers of the comments section of that page.
Resolve Comments
After you finish a comment, you can resolve it to hide the details. Resolving a comment will notify the watchers about its status.
Publishers and admins can address all comments at the same time.
You can set up Ask before Publishing if you want to publish only when all comments are resolved.
Watch/Mute
When you comment on a page or get tagged in one, you automatically become a watcher of that page. As a watcher, you receive updates about all comment activity on the page.
As a watcher, you will receive email notifications summarizing the updates and changes made to the page comments.
To unwatch a page at any time:
- Open the Activity sidebar of the page.
- Toggle Watch into Mute.
To resubscribe, toggle Mute into Watch.
You can also unsubscribe from all activity notifications by navigating to the User Settings.