Comments on diagrams
Feedback on a diagram usually ends up in a page comment that says "the box on the left", or in a chat thread nobody can find later. Diagram comments keep the conversation on the diagram, where the next person to open it will see it.
They are ordinary Confluence footer comments stored on the diagram, so Confluence decides who can read and write them, and an @mention sends the usual Confluence notification.
#Where you see comments
Where | What you see |
|---|---|
A diagram on a page | Once a diagram has comments, a yellow button with the count is the first button in its toolbar. Select it and the diagram opens full screen with the comments already open. Past 100 it reads 100+. A diagram with no comments shows nothing extra. |
The full-screen view | A speech bubble Comments button sits next to the download and share buttons. It is plain while there are no comments, and turns yellow with the count once there are. |
The Capable Diagrams catalogue | Open any diagram from Diagrams on pages or a collection and the same Comments button is there. |
Only stored diagrams can have comments. Built-in examples and a diagram you have not saved yet have no Comments button.
#Adding a comment
On the page, hover over the diagram and select Maximize, or select the comment count if there is one. In the full-screen view, select Comments. The comments sidebar opens on the right, oldest comment at the top and newest at the bottom.
Type in the box at the bottom, which says Comment on this diagram…. The box shows your formatting as you type.
Type | What you get |
|---|---|
| A list of people to mention. Pick one and Confluence notifies them. You can also use the Mention someone (@) button. |
| A list of pages and blog posts to link. Before you type, it shows pages you viewed recently. You can also use the Link a page (/) button. |
| Bold. |
| Italic. |
| A link with your own label. |
Enter | A new paragraph. |
@ and / only open their lists at the start of a line or after a space, so an email address or a date does not trigger them.
Select Comment, or press Cmd+Enter on a Mac or Ctrl+Enter on Windows. The comment appears at the bottom of the list and the count on the button goes up.
#Who can do what
Action | Who |
|---|---|
Read comments | Anyone who can view the diagram. |
Add a comment | People who can edit the diagram, which normally means people who can edit the page it is on. Everyone else sees Only people who can edit this diagram can comment. |
Edit a comment | Only the person who wrote it, using Edit comment on their own comment, then Save. |
Delete a comment | Not offered in the comments sidebar. |
Some comments can be read but not edited here. Capable only offers Edit comment when saving would keep your comment exactly as it was. Comments that hold lists or tables, text that looks like formatting (a literal **word** typed in another editor), two mentioned people with the same display name, or links whose address contains spaces or brackets stay read-only, so nothing changes by accident.
#Where comments are stored
Each comment is a Confluence footer comment on the diagram's own content, not on the page around it. That has a few consequences worth knowing.
Confluence checks every read and write as you, so nobody sees a comment on a diagram they cannot view.
Mentions and page links are real Confluence mentions and links, not text that looks like them.
A diagram shown on several pages through a reference keeps one conversation, wherever you open it.
Comments use the comment permissions the app already had. No new permission was added for them. See Scopes and permissions.
#A few things that catch people out
Nothing refreshes on its own. To see comments other people added while you had the sidebar open, select Refresh at the top of it. The count on the page updates when you close the full-screen view.
The comments sidebar and the AI chat share the right-hand side, so opening one closes the other. The Details panel folds away while comments are open and comes back when you close them.
If you edit a comment that someone else changed in the meantime, you get This comment changed since you opened it. Reload and try again. Nothing is overwritten.
Moving from the standalone Capable Diagrams app to the Capable suite copies diagrams but not their comments.
Comments are not diagram versions. Adding one does not change the diagram or its history.
#Related
Diagram macro reference
The toolbar where the comment count appears.
Diagram permissions
Who can view and edit a diagram.
Update a diagram
Changing the diagram itself.
Diagram version history
Every save, and how to go back.
Add comments to a diagram in Confluence
The short step-by-step version.
Mention someone in a diagram comment
Pull the right person in.
The conversation stays with the diagram it is about.
