Comments on a block

Comments let your team talk about the manual inside the editor. Each one sits under a section, and can point at one block in that section. Readers never see them.

Where the comments are

WhereDashboard, Brand manual, Content, under every section

Every section has its own comments. A section nobody has written on shows one Add a comment line. Once there is something to read, it becomes a card headed Comments with a count of open threads and total comments, plus Show or Hide on the right.

There is no page listing every comment in a brand. You read them under the section they were written on.

Starting a thread

1. Open the comments with Show or with the Add a comment line.
2. Choose what the comment is About. The list starts with The whole section, then names every block in the section, numbered in the order they appear. A section with no blocks has no About control, and the comment is about the section.
3. Type into the box labeled Leave a comment for your team.
4. Press Comment. It reads Posting... and is disabled while it saves, so you cannot post the same text twice.

The comment appears at the bottom of the list with your name, the time, and a tag naming the block when it is about one. Comments are ordered oldest first.

What a comment is about

The block names in the About list are the same names the editor uses.

Reordering blocks changes nothing: the comment follows the block it named. If that block is removed from the section, the comment stays and its tag reads a removed block.

Replying

Every open thread has a Reply button under it, which turns into Cancel reply while the box is showing.

• Threads are one level deep. An answer to an answer joins the same thread under the same first comment.
• A reply takes its parent's subject. You do not choose a block for a reply.
• A resolved thread cannot be replied to. The Reply button is not shown on one. Reopen it first.

Who is mailed

Everyone who has written in that section is mailed, once each, except the person who just wrote. A section nobody has commented on sends no mail. An account without a usable address is left out.

Ada Lovelace commented on "Colors" in Acme Brand Manual

A reply says replied where a new thread says commented. The body repeats that line, names the block when there is one, then gives the comment and a link straight to that section of the editor.

Resolving a thread

Resolve thread closes the first comment and every reply under it together. You cannot resolve a single reply on its own.

A resolved thread is dimmed, carries a green Resolved tag, loses its Reply button, and stops counting toward the open count in the card heading. Nothing is deleted. The same button reads Reopen thread and puts the thread back as it was, replies included.

Who may do what

Writing a comment needs View the brand manual, which every built-in role has. Resolving, reopening and deleting somebody else's comment need Edit sections and content. Deleting your own comment needs neither.

A viewer can ask a question, answer one, and delete what they wrote themselves, without being able to change the manual. A custom role is judged on those two permissions, not on its name. See Roles and Custom roles.

Deleting a comment

Delete sits beside the time on your own comments always, and on anybody's if you may edit the manual. It asks first, under the title Delete this comment?, and the confirmation button reads Delete comment.

• Deleting is permanent. Comments are not kept in the trash, so there is nothing to restore one from.
• Deleting the first comment of a thread deletes the replies under it. The dialog counts them before you confirm.
• Deleting a reply leaves the thread standing. Only that one comment is removed.

Where comments do not appear

Comments live in the editor and nowhere else. If you want readers to see something, put it in a block.

The limits of one comment

• 2000 characters. The box stops you at that length.
• Plain text. No formatting controls and no attachments. Your line breaks are kept as you typed them.
• An empty comment is not posted. Whitespace on its own counts as empty.
• Comments cannot be edited. Delete and write it again, or reply.

What happens when the manual changes

Names on old comments

A comment keeps the name of whoever wrote it, including people who have left the team. When an account is deleted, the comments stay with the brand and the name on them becomes Deleted account.

Anyone downloading their own data under Account (opens in a new tab) gets their comments in that file. See Your account.