On this page

What review comments are for#

Review comments let your team discuss an article where it is written. A reviewer can point at a wrong step, ask the author a question, or suggest a better title, and the conversation stays with the article instead of in chat or email. A comment can be about the article as a whole, or pinned to the exact words it discusses.

Comments live in the article editor. Every comment starts as an internal note: internal notes never appear in the Library, on the customer portal, or in anything a customer receives.

The same panel also holds the conversation with customers when an article allows it. Members who hold Send Public Replies can choose Public comment instead of Internal note, and customers can comment from the portal; their comments carry a Customer badge here. See Customer comments on articles.

On a customer's own client spec draft, a public comment is always visible to everyone signed in from that customer's company, whether or not customer comments are switched on. The comment box says so when you choose Public comment there.

Turn it on by granting a permission

In an established organization, nobody except the Owner and Admins can comment until an administrator grants Comment on knowledge-base articles to a role. Grant Moderate knowledge-base article comments as well to people who should be able to tidy up anyone's comments. See Knowledge Base permissions.

The Comments panel#

Open an article from Manage articles. The Comments panel sits in the editor's right-hand sidebar, below History, and starts open. Its heading always shows how many threads are still open: the number in a red badge followed by open, or None when nothing is waiting. Like every panel in the sidebar, it folds away when you click its heading (see Fold, widen or hide the sidebar).

Three buttons at the top choose which threads to list:

  • Open — threads still waiting on someone. This is the default.
  • Resolved — threads that have been dealt with.
  • All — both.

Each thread is a card. Threads pinned to words in the article come first, in the order their words appear, each marked with its number and showing the words it quotes at the top of the card. The rest follow, oldest first, each opening on its author line. Click Load more at the bottom to see older pages. A long list scrolls inside the panel, so the comment box stays in reach below it.

The Resolve icon (a check mark) sits at the top right of a card: beside the quote on a pinned thread, in the corner beside the author line on a general one.

Click a card, or move to it with the keyboard, to choose it. Its border is highlighted and its comments show their actions in their footers: Reply, Edit, Delete and reactions, as one row of icons. Hover an icon to see its name. Until you choose a card its actions stay hidden, so the list reads as a conversation.

Anyone who can open the article in the editor can read its comments.

Writing a comment#

Type in the box at the bottom of the panel (Add a comment...) and click Comment. Each comment starts a thread; click Reply on a comment to answer inside its thread.

To write, you need Comment on knowledge-base articles and at least Can comment on the article (the level every member has unless the article's sharing says otherwise). If you are missing the permission, the panel says Commenting needs the Comment on knowledge-base articles permission. Archived articles cannot take new comments.

You can edit or delete your own comments, and react to anyone's, just as on a work item.

Pinning a comment to words in the article#

When a comment is about one step, sentence or phrase, pin it to those words so nobody has to guess what it means.

  1. In the article, select the words the comment is about. Your next comment pins to them by itself: the comment box shows Commenting on: followed by the words you chose. Until you select something, the box reads Select text to pin.
  2. Write your comment and click Comment. The words stay chosen while you type in the Comments panel.

To go back to a comment on the whole article, click the × beside the quoted words (its tooltip says Clear the pin), or click anywhere in the article without selecting. Selecting other words pins to those instead.

The words are now highlighted in the article, with a small number after them. The same number sits on the comment's thread in the sidebar, so 1 is always the pinned passage nearest the top. Pinned threads show the words they quote at the top of their card.

  • From the text to the comment: click highlighted words to bring up their comment; its card flashes so you can spot it. If the sidebar or the Comments panel is hidden, it opens again.
  • From the comment to the text: click the quote on a thread (its tooltip says Show in text). The article scrolls to the words and marks them.

Some limits:

  • Only a new thread can be pinned. Replies belong to the thread and cannot be pinned on their own.
  • A passage can be up to 500 characters. Select more and the panel says Select a shorter passage (up to 500 characters).
  • If you have unsaved changes in the article, they are saved first, so the comment pins to the words everyone sees. If they cannot be saved, the comment is not posted.
  • Pinning does not count as editing the article: it adds no version to the article's history, and you can pin on an article you can comment on but not edit.
  • If the words changed while you were writing (a teammate edited that sentence, say), you see That text has changed. Select it again. and nothing is posted.

A pinned internal note is highlighted only in the article editor: customers never see it, or its highlight, in the portal. A pinned public comment is highlighted for customers too, wherever they can see the comment (see Customer comments on articles).

When the pinned words change#

Pins survive editing. A pin moves with its words when text around them changes, and stays in place when someone saves the article from an older editor tab, rewrites other parts of it, or replaces the whole text through the API or an AI assistant, as long as the pinned words themselves are still there. DevStride never moves a comment onto the same words somewhere else in the article.

When the pinned words are deleted or reworded, or DevStride cannot tell which of two identical passages was kept, the comment stays. Its card keeps the quote, struck through, and says Passage removed, so you can still read what it was about. Its number goes away, and it is listed after the pinned threads.

When a pinned comment is deleted#

Deleting a pinned comment takes its highlight and number out of the article too, in the editor and in the portal, and the other pins renumber. Removing the highlight is not an edit: it adds nothing to the article's history. If the comment still has replies, it stays as This comment was deleted. with its highlight, until its last reply is deleted too.

Mentions and notifications#

Type @ and a name to mention a teammate. DevStride notifies:

  • the article's author, when someone starts a new thread on their article (under their own preference for comments on things they created);
  • anyone you @mention;
  • on a reply, the person who started the thread, everyone who replied before, and people mentioned in it;
  • people who watch the article or a category above it, if they ticked Watcher for Comments modified.

Each person hears about a comment once, and never about their own.

Notifications arrive in the app and by email, Slack, or Microsoft Teams according to each person's notification settings. Following one opens the article editor at that comment. Nobody is notified about an article they cannot read.

The panel also updates live: comments others post, edit, or delete appear while you have the article open.

Resolving a thread#

When a thread has been dealt with, click the Resolve icon (a check mark) at the top right of its card. A resolved thread folds down to one line, Resolved by name · when, with an Expand icon to read it again and a Reopen icon to put it back in the open list.

The person who started the thread can resolve and reopen it. Holders of Moderate knowledge-base article comments can resolve and reopen any thread.

On Manage articles, an article with unresolved threads shows a chip such as 3 open beside its title, so authors can see at a glance which articles have feedback waiting.

Reviewers who do not write articles#

You can give someone Comment on knowledge-base articles without any authoring permission. They can open Manage articles and the editor, including other members' drafts they can read, so they can review an article before it is published. The editor shows the article to them read-only, with the note You can read and comment on this article, but not edit it. Only the Comments panel is active for them, and they can still select words and pin a comment to them.

Moderating comments#

Holders of Moderate knowledge-base article comments can edit, delete, resolve, and reopen anyone's comments on articles they can see. Moderating comments on work items is a separate permission and does not reach article comments.

Powered by DevStride