[Docs] Improve clarity and consistency of comment notification behavior in Kanvas documentation

[Bhumikagarggg]

Current State

While testing and validating the comment notification system in Kanvas, I reviewed the documentation

Most scenarios are well documented; however, a few areas could benefit from additional clarification to better reflect the intended behavior and reduce ambiguity.

---

Observations

1. Owner Notification Behavior Needs Explicit Clarification

• Documentation states that design owners receive notifications for all comments
• However, it does not clearly explain how muting applies to owners

From testing:

• Global notification preferences (Cloud settings) are respected for owners
• Thread-level muting does not suppress notifications for owners

This distinction is not explicitly documented and may lead to confusion.

---

2. Muting Behavior Differs by User Role

• Docs mention that muted users do not receive notifications
• In practice:
  • Non-owners → muting works as expected
  • Owners → continue to receive notifications at thread level

This difference appears intentional but is not clearly documented.

---

3. Missing Notification Control Hierarchy

• The relationship between different levels of control is not clearly defined:
  • Global preferences (Cloud settings)
  • Thread-level muting

A clear hierarchy (e.g., Global > Thread, with role-based behavior) would improve understanding of how these controls interact.

---

4. Tagging Behavior Could Be Better Structured

• Documentation mentions that tagged users do not receive notifications if muted
• However, behavior across:
  • Thread-level muting
  • Global preferences
  • Owner role

could benefit from clearer, scenario-based explanations.

---

Suggested Improvements

• Explicitly document owner-specific notification behavior
• Clarify differences between owner and non-owner muting behavior
• Introduce a clear hierarchy of notification controls
• Add structured examples covering edge cases (muted + tagged, multi-user scenarios, etc.)

---

Contributor Guide and Resources

• 📚 Instructions for contributing to documentation
  • Layer5 documentation site and source
• 🎨 Wireframes and designs for Layer5 site in Figma (open invite)
• 🙋🏾🙋🏼 Questions: Layer5 Discussion Forum and Layer5 Community Slack