diff --git a/content/en/kanvas/designer/comments/example-notification-email.png b/content/en/kanvas/designer/comments/example-notification-email.png new file mode 100644 index 00000000..90e70bb4 Binary files /dev/null and b/content/en/kanvas/designer/comments/example-notification-email.png differ diff --git a/content/en/kanvas/designer/comments/index.md b/content/en/kanvas/designer/comments/index.md index df95c5c8..b6f48c81 100644 --- a/content/en/kanvas/designer/comments/index.md +++ b/content/en/kanvas/designer/comments/index.md @@ -17,6 +17,8 @@ Kanvas's Designer offers enables you to place comments "inline" with your infras
Example of comments in Designer
+Your comment may be a request for design review, to offer feedback to peers, or to simply record notes. + ## Commenting on a Design You can add comments in a number of convenient ways. Since designs are public by default, you can add comments to your designs without having to share them first. This is particularly useful for gathering feedback from team members or stakeholders before finalizing the design. @@ -51,9 +53,13 @@ Context-click on any area of your design, and from the contextual menu, select "
Peer review using comments in Designer
-### Initiate Threads +### Conversations in Comment Threads + +Any number of users can participate in a single comment. When more than one user makes a remark in the same comment, a comment thread ensues. -You can initiate a comment thread by just adding a comment. Your comment may be a request for design review or feedback on a design. Team members can reply directly to comments to for a comment thread. This creates a structured dialogue around each point of feedback for easy referencing. +When a new thr is added, existing comments are typically pushed down within the same comment thread. This means that the new comment appears at the bottom of the thread, with earlier comments remaining visible but lower in the list. + +Initiate a comment thread by just adding a remark on an existing comment. Collaborators can reply directly to comments in real-time (approximating a chat). Comment threads create a structured dialogue around each point of feedback for easy reference. ### Utilize Mentions @@ -63,13 +69,17 @@ Easily draw the attention of relevant team members by tagging them in your comme Leave comments on specific elements within the design, whether it's a shape, text, or an entire component. This specificity ensures that feedback is targeted and directly related to the part of the design under discussion. -### Avoid Dangling Threads / Resolving Comment +### Resolving a Comment -Once revisions are complete, you can resolve the comment. This action closes the comment thread and signifies that the conversation around that feedback has concluded. +Resolving a comment thread indicates that the conversation on that topic has concluded. When a comment is resolved, the comment component is removed from view on the canvas. -### View Comment History +As a practice, resolving comments can help expedite issue resolution on a particular topic. The action of resolving a comment is like a "soft delete" in that Kanvas designs retain history of each comment made and discussions within. -After resolving a comment thread, you can access the comment history to review previous discussions and decisions. This is particularly useful for tracking changes and understanding the evolution of the design. +This retained history is kept as an archived copy of the comment within your design document. You can access this comment history to review previous discussions and decisions. A best practice is to resolve comments rather than delete them, specifically for the benefit of having a historical reference of prior notes, discussions, and decisions. + +You can also reopen comments. + +### View Comment History
View comment history @@ -78,21 +88,39 @@ After resolving a comment thread, you can access the comment history to review p Manage your comment history by clicking on the "View Comment History" button. This allows you to revisit past discussions and decisions, ensuring that important context is never lost. -## Managing Comment Notifications - -### Enable Email Notifications +### Reopening (unresolving) Comments -Customize your [notification preferences](/cloud/identity/users/notification-preferences) to receive emails for comments on your design. When this is enabled, you'll be notified when comments are made on your design, you're mentioned in a comment, or someone adds a comment to a thread you've previously engaged with. +After a comment has been resolved, you might need to reopen the discussion. Reopening a comment allows you to reinitiate conversations, address additional concerns, or make further changes. -### Unresolving (reopening) Comments +If a comment is resolved by mistake, it can be reopened. Adding a new comment to a resolved discussion will also re-open the thread. -After a comment has been resolved, there might be situations where you need to reopen the discussion. Unresolving a comment allows you to reinitiate conversations, address additional concerns, or make further changes. Follow the steps below to unresolve a comment: +Follow the steps below to reopen a comment:
Unresolving comments in designer
Unresolving comments in designer
+## Managing Comment Notifications + +Each time that a new comment is made in a design, remark placed into existing comment, a comment is resolved or reopened, you and your collaborators might receive notification via email. + + +
+Example email notification received when design comment is made +
Example email notification received when design comment is made.
+
+ +As the owner of a design, you will recieve notification each time a comment is made in your design. Tag other users and have them receive notificaiton of your comment by mentioning their username with the `@` symbol. + +All users participating in a comment will be notified as new remarks are added in a comment thread. + +As new comments are added into the your design, collaborators (other users) with which you have shared the design, will not receive notification unless they are tagged in that comment. + +### Enable Email Notifications + +Customize your [notification preferences](/cloud/identity/users/notification-preferences) to receive emails for comments on your design. When this is enabled, you'll be notified when comments are made on your design, you're mentioned in a comment, or someone adds a comment to a thread you've previously engaged with. + ### Mute Comment Notifications Customize your notification preferences to mute email notifications for comments on your design. With notifications for new comments silenced, you won't receive email notifications for new comments on your design. This can be useful if you want to temporarily pause notifications or reduce email clutter. @@ -118,6 +146,10 @@ Customize your notification preferences to mute email notifications for comments - You'll never miss an important mention, as notifications for mentions outside the muted thread remain active. {{< /alert >}} +{{< alert type="info" title="Tip">}} +Currently, the system does not track read or unread messages inside comment threads for each user. If a user is mentioned but misses the notification, they might not become aware of the mention until they receive a new notification for another comment in that conversation. +{{< /alert >}} + ## Best Practices for Effective Design Reviews ### Be specific and actionable