maxsuite Diagrams

Comments

Comments

Comments is the review conversation on documentation pages: notes left on a page while it is in draft, replies to them, and resolving each thread when its point is dealt with. Comments are kept apart from the page text, because they are about the draft rather than part of it.

In the sidebar under Content → Comments. Needs: Pages.

Where comments show

There are two places to see comments.

Beside a page, in Pages: under the editor, a Comments card lists the threads on that page, each with its replies. Every thread has Reply and Resolve (or Reopen once resolved), and a box at the bottom takes a new comment.

Comments screen

The Comments entry in the sidebar lists every comment you may see, replies and removed comments included:

  • each row shows the comment, the passage it quotes (if any), the page's id, whether it is resolved (open until it is), and when it was left;
  • at the top: how many comments there are, how many are open, and on how many pages;
  • Edit and Delete on each row.

You only see comments on pages you are allowed to open. Comments on a page you cannot read are left out.

This screen also shows New comment, Resolve and Reopen, but they do not go through from here: leave, resolve and reopen comments from the Comments card beside the page in Pages.

Comment on a passage

  1. Open the page in Pages and switch to Markdown or Split.
  2. Select the passage the comment is about. The selection is quoted with the comment.
  3. Type in the box under Comments and click Comment.

The quoted passage is a snapshot, not a live link. If the page text changes later, the quote still shows what was there.

Reply, resolve and reopen

  1. Click Reply on a thread, type, and click Reply.
  2. Click Resolve when the point is dealt with, or Reopen to bring it back.

Correct or remove a comment

  1. Open Content → Comments and find the comment.
  2. Click Edit to reword it. Only the text changes: the page and the quoted passage stay as they were.
  3. Or click Delete to take it down.

Only a comment's author, or an administrator, may reword it or take it down. Removing a comment cannot be undone. A removed comment leaves the card beside its page, but still shows in the list on the Comments screen.

Who can do what

PermissionLabelLets you
comments:readView commentsSee comments on pages you may open, and the Comments card beside each page.
comments:writeManage commentsLeave comments and replies, resolve and reopen threads, and reword or remove your own comments.

The author of a comment is always the person signed in, never a name typed into a form. See People, roles and permissions.

Comments on diagrams are part of Diagrams, and comments on documents are part of Documents. Neither goes through this module.

What happens on its own

Nothing in this module runs on a schedule.

What agents can do

An agent can read the threads on a page, leave comments and replies, and resolve them. Reads run straight away. Changes wait for a person's approval by default (Agents and approvals).

Read only: comments.list

Write: comments.create, comments.resolve, comments.edit

Remove (cannot be undone): comments.remove

comments.create can carry a quoted passage. comments.edit changes only the text, and only for the comment's author or an administrator. comments.remove is the same. Over MCP the same tools are named comments__list, comments__create and so on. See API keys and MCP access.