Test And Accept
Features

Commenting

Discuss and collaborate on work with your team

Commenting enables real-time collaboration by letting you discuss work directly where it happens. Add feedback, ask questions, provide clarifications, and have threaded conversations on statements of work, work items, criteria, and tests.

What is Commenting?

Commenting helps you:

  • Discuss Work: Have conversations directly on the work items
  • Provide Feedback: Share thoughts and suggestions in context
  • Ask Questions: Get clarification without leaving the page
  • Track Decisions: Document why choices were made
  • Mention Teammates: Notify specific people for input
  • Resolve Issues: Mark comments as addressed when done
  • Maintain Context: Keep discussions tied to specific items

Where You Can Comment

Comment Locations

Statements of Work:

  • General SOW comments (overall scope, approach)
  • SOW-level discussions
  • Planning and strategy conversations

Work Items:

  • Requirements, tasks, milestones
  • Implementation questions
  • Clarifications on scope
  • Status updates and blockers

Acceptance Criteria:

  • Definition questions
  • Test case discussions
  • Acceptance conditions

Tests:

  • Test procedure questions
  • Expected results clarification
  • Test environment discussions

Adding Comments

Create a Comment

  1. Navigate to the item (SOW, work item, criterion, or test)

  2. Find the comments section (usually at the bottom or side panel)

  3. Click "Add Comment" or type in the comment box

  4. Write your comment:

    • Be clear and specific
    • Provide context if needed
    • Ask direct questions
    • Suggest actionable improvements

  5. Click "Post" or "Submit"

Example comments:

Good comments:

✓ "Should this support tablets as well as phones?
   Our analytics show 30% tablet traffic."

✓ "This conflicts with the security requirement in Section 2.
   How should we reconcile these?"

✓ "Approved, but please update the timeline in the description
   to reflect the 2-week extension we discussed."

Less helpful comments:

✗ "Looks good"
✗ "?"
✗ "See my email"

Comment Formatting

Use formatting for clarity:

Bold for emphasis:

**Important**: This needs client approval before proceeding.

Lists for multiple points:

Three concerns:
1. Timeline seems optimistic
2. Missing mobile requirements
3. No mention of accessibility

Code blocks for technical details:

The API endpoint should be:
`GET /api/v2/users/{id}`
not
`GET /users/{id}`

Links for reference:

See related discussion: [RFC-2024-042](/rfcs/042)
Client feedback: [Meeting notes](https://...)

Threaded Conversations

Reply to Comments

Continue the conversation:

  1. Find the comment you want to respond to
  2. Click "Reply"
  3. Write your response
  4. Post reply

Thread structure:

💬 Jane Smith - 2 hours ago
   "Should this include tablet support?"

   ↳ 💬 John Doe - 1 hour ago
      "Yes, analytics show 30% tablet users."

      ↳ 💬 Jane Smith - 30 minutes ago
         "Great, I'll add tablet-specific criteria."

Benefits of threading:

  • Keeps conversations organized
  • Easy to follow discussions
  • See decision progression
  • Maintain context

Multiple Participants

Conversations can include many people:

💬 Product Owner
   "Need this by end of quarter."

   ↳ 💬 Tech Lead
      "That's ambitious. Here's why..."

      ↳ 💬 Product Owner
         "Can we prioritize core features?"

         ↳ 💬 Developer
            "Yes, if we defer the reporting module."

            ↳ 💬 Product Owner
               "Agreed. Let's update the SOW."

Mentioning Users

Notify Specific People

Use @ mentions to notify someone:

In a comment:

@jane Can you review the mobile requirements?
We need your UX expertise here.

@john This affects the API you're building.
Please confirm the endpoint structure works.

What happens:

  • Mentioned user receives notification
  • Email sent (if notifications enabled)
  • Highlights their name in the comment
  • Shows in their notifications panel

When to mention:

  • Need specific person's input
  • Escalating an issue
  • Requesting approval
  • Asking for clarification
  • Assigning action items

Mention Multiple People

Notify a whole team:

@team-frontend @team-backend

We need to coordinate on this integration.
Frontend team: API spec ready for review
Backend team: Can you confirm timeline?

Comment Status

Marking Comments as Addressed

Comments can have status:

  • Open: Needs attention or response
  • Addressed: Issue resolved or question answered
  • Rejected: Suggestion declined (with reason)

To mark as addressed:

  1. Resolve the issue raised in comment

  2. Reply with resolution:

    Good catch! I've updated the criterion to include
tablet support. See updated v5.

  3. Click "Mark as Addressed" or "Resolve"

Addressed comments:

  • Move to "Resolved" section
  • Gray out or collapse
  • Still searchable
  • Can be reopened if needed

Reopening Comments

If an issue returns:

  1. Find the addressed comment

  2. Click "Reopen"

  3. Add explanation:

    Reopening: Client meeting revealed tablets
need different approach than originally planned.

  4. Comment returns to "Open" status

Comment Organization

Filtering Comments

View specific types of comments:

By status:

  • Show only open comments
  • Show only addressed comments
  • Show all comments

By author:

  • Show only my comments
  • Show comments by specific user
  • Show comments by client contacts

By date:

  • Show recent comments (last 7 days)
  • Show comments in date range
  • Show oldest unaddressed comments

By item type:

  • Show SOW-level comments only
  • Show item-level comments
  • Show criterion comments
  • Show test comments

Sorting Comments

Order comments by:

  • Newest first (default)
  • Oldest first
  • Most replies
  • Unresolved first
  • Mentioned user first

Searching Comments

Find specific discussions:

  1. Click "Search Comments"

  2. Enter keywords:

    • "security"
    • "approved"
    • "blocker"
    • "@jane"

  3. See matching comments with context

  4. Jump to full thread

Comment Notifications

Receiving Notifications

You get notified when:

  • Someone mentions you (@username)
  • Someone replies to your comment
  • Someone comments on item you own
  • Someone comments on item you're following
  • Status changes on comment you're involved in

Notification channels:

  • In-app notification badge
  • Email (configurable)
  • Desktop notification (if enabled)
  • Mobile push (if app installed)

Managing Notifications

Control what you're notified about:

  1. Go to notification settings

  2. Configure preferences:

    • All comments on my items
    • Only mentions and replies
    • Only critical items
    • Digest mode (daily summary)

  3. Per-resource settings:

    • Follow this SOW (get all notifications)
    • Unfollow this SOW (stop notifications)
    • Mute this thread (stop replies)

Comment Best Practices

Writing Effective Comments

Do:

  • Be specific and actionable
  • Provide context
  • Ask clear questions
  • Suggest solutions, not just problems
  • Use formatting for clarity
  • Reference related items
  • Be respectful and professional

Don't:

  • Just say "looks good" (not helpful)
  • Write vague comments
  • Use comments for private conversations
  • Post sensitive information
  • Be unclear or ambiguous
  • Forget to mention relevant people

Examples of Good Comments

Asking for clarification:

💬 "The acceptance criterion mentions 'fast page load'
   but doesn't specify a target. Should this be under
   2 seconds? Under 1 second? We need a measurable goal
   to properly test this. @product-owner"

Providing feedback:

💬 "This requirement looks solid, but I suggest adding:
   1. Error handling for network failures
   2. Fallback for unsupported browsers
   3. Accessibility requirements for screen readers

   These came up in our last security review."

Documenting decisions:

💬 "Decision from 12/15 client meeting: We're proceeding
   with Option B (React-based implementation) instead of
   Option A. Rationale: Better matches client's existing
   tech stack and internal team expertise.

   See RFC-2024-038 for full analysis."

Reporting blockers:

💬 "🚫 BLOCKER: Can't proceed with this task until we
   receive API credentials from the client. Requested on
   12/10, following up today. @project-manager can you
   escalate with client contact?"

Comment Etiquette

Be constructive:

✓ "This approach might cause scaling issues. Have we
   considered caching? I can share some patterns
   that worked on Project X."

✗ "This won't work."

Be specific:

✓ "The 'user authentication' requirement is too broad.
   Should this include: OAuth? SSO? 2FA? Password reset?
   Let's break this into separate items."

✗ "This needs more detail."

Be timely:

  • Respond to questions within 24 hours
  • Mark comments as addressed when done
  • Don't let open comments pile up
  • Follow up on blockers quickly

Comment Workflows

Code Review Pattern

Use comments like code reviews:

💬 Reviewer: "This requirement seems to duplicate
   Section 3.2. Can we consolidate?"

   ↳ 💬 Author: "Good catch. I'll remove this and
      add a reference to 3.2 instead."

   ↳ 💬 Reviewer: "Perfect, marking as addressed."
   [Resolved]

Client Approval Pattern

Document approvals in comments:

💬 Developer: "Ready for client review.
   @client-contact please review and approve."

   ↳ 💬 Client: "Looks good overall. Two requests:
      1. Add quarterly reporting
      2. Include data export feature"

   ↳ 💬 Developer: "Added both as new requirements.
      See updated v4. Ready for re-review."

   ↳ 💬 Client: "Approved! ✅"
   [Resolved]

Team Collaboration Pattern

Coordinate across team:

💬 Product: "Need technical feasibility assessment.
   @tech-lead @architect thoughts on this approach?"

   ↳ 💬 Tech Lead: "Feasible but will need 3 weeks.
      Requires new infrastructure."

   ↳ 💬 Architect: "Agree with timeline. I can help
      with infrastructure design."

   ↳ 💬 Product: "Great, I'll update timeline and
      add infrastructure task. Thanks team!"
   [Resolved]

Advanced Features

Comment Templates

Save common comment types:

Approval template:

✅ **APPROVED**

Reviewed: [Date]
Approved by: [Name]
Notes: [Any conditions or comments]

Blocker template:

🚫 **BLOCKER**

Issue: [Description]
Impact: [What's blocked]
Needed: [What's needed to unblock]
Owner: @[username]
Deadline: [Date]

Question template:

❓ **QUESTION**

Question: [Your question]
Context: [Why you're asking]
Impact: [What depends on answer]
For: @[username]

Comment Export

Export comments for documentation:

  1. Open item with comments

  2. Click "Export Comments"

  3. Choose format:

    • PDF (for sharing)
    • CSV (for analysis)
    • JSON (for backup)

  4. Select filters:

    • All comments or only open
    • Date range
    • Specific authors

Use exported comments for:

  • Meeting documentation
  • Audit trails
  • Client reports
  • Team retrospectives

Comment Analytics

Track comment activity:

Metrics you can see:

  • Total comments per SOW
  • Average response time
  • Most commented items
  • Open vs. resolved ratio
  • Comments by user
  • Comments over time

Use analytics to:

  • Identify contentious areas
  • See collaboration patterns
  • Improve response times
  • Recognize active contributors

Troubleshooting

Comments Not Showing

If comments aren't visible:

  • Check your filter settings
  • Verify you have access to view comments
  • Try refreshing the page
  • Check if comments are collapsed
  • Ensure you're viewing correct version

Can't Add Comments

Possible reasons:

  • Don't have comment permissions
  • Item is locked (in approval)
  • SOW is archived
  • Comment feature disabled for item type

Solutions:

  • Request appropriate access level
  • Wait for approval to complete
  • Unarchive SOW if needed
  • Contact admin about permissions

Notifications Not Working

Check these settings:

  • Notification preferences enabled
  • Email address correct
  • Not in "do not disturb" mode
  • Browser notifications allowed
  • Email not in spam folder

Can't Mention User

Possible reasons:

  • User not part of project
  • Username spelled incorrectly
  • User doesn't have access
  • Mentions disabled

Solutions:

  • Grant user access first
  • Check username spelling (@jane not @Jane)
  • Verify user permissions
  • Check system settings

Access Control

Email Distribution

Change Management

Versioning