---
title: "Commenting"
description: "Discuss and collaborate on work with your team"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.testandaccept.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commenting

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

## Related Features

- **Access Control**
- **Email Distribution**
- **Change Management**
- **Versioning**

Source: https://docs.testandaccept.com/features/commenting/index.mdx