Comments

Discuss and collaborate on documentation using comments.

What are Comments?

Comments enable team discussions directly on documentation files. Use them to:

• Ask questions about content
• Suggest improvements
• Provide feedback
• Discuss changes
• Coordinate with teammates

Types of Comments

File-Level Comments

General discussions about the entire file:

1. Open a file
2. Click Comments in the sidebar
3. Type your comment
4. Click Post

File comments appear in the main comments section.

Version-Specific Comments

Comments about specific versions:

1. Open Version History
2. Select a version
3. Click Comment on This Version
4. Type your comment
5. Click Post

Version comments stay attached to that version.

Creating Comments

Write a Comment

1. Navigate to Comments section
2. Click in the text box
3. Write your comment (Markdown supported)
4. Click Post or press Cmd/Ctrl + Enter

Formatting Comments

Use Markdown for rich formatting:

**Bold text**
*Italic text*
`code`
[Link](https://example.com)

- Bullet list
- Another item

> Quote

Mentioning Team Members

Coming soon: Mention teammates with @username to notify them.

Managing Comments

Edit Your Comment

1. Find your comment
2. Click Edit (⋯ menu)
3. Modify the text
4. Click Save

Edited comments show "(edited)" indicator.

Delete Your Comment

1. Find your comment
2. Click Delete (⋯ menu)
3. Confirm deletion

Deleted comments cannot be recovered.

Reply to Comments

Create threaded discussions:

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

Replies appear indented under the original comment.

Comment Threads

View Threads

Comment threads show:

• Original comment
• All replies indented
• Timestamps for each message
• Author names
• Read/unread status

Collapse Threads

Hide long conversations:

1. Click the Collapse button on the parent comment
2. Thread is hidden
3. Click Expand to show it again

Comment Notifications

Get notified about comment activity:

Notification Settings

1. Navigate to Settings → Notifications
2. Configure comment notifications:
   • New comments on files you created
   • Replies to your comments
   • Mentions (coming soon)

Notification Channels

Receive notifications via:

• In-app notifications
• Email notifications
• Slack notifications (Professional plan+)

Comment Best Practices

Be Specific

Reference specific content:

• ✅ "In the Authentication section, should we mention OAuth 2.0?"
• ✅ "Line 23: This example uses deprecated syntax"
• ❌ "This needs work"
• ❌ "Update this"

Use Constructive Language

Frame feedback positively:

• ✅ "Consider adding an example here for clarity"
• ✅ "This section could be expanded to cover edge cases"
• ❌ "This is wrong"
• ❌ "Bad explanation"

Respond Promptly

Keep discussions moving:

• Respond to comments within 24-48 hours
• Keep threads focused
• Take complex discussions offline if needed

Tag Comments

Use tags to categorize comments:

• [question] - Asking for clarification
• [blocker] - Must be addressed before publishing
• [nice-to-have] - Optional improvements

Comment Permissions

Who Can Comment

• Owner, Admin, Editor - Can comment on any file
• Viewer - Can read comments, cannot create

Who Can Edit/Delete

• Comment author can edit/delete their own comments
• Workspace Owners and Admins can delete any comment
• Others cannot modify comments

Comment History

All comments are preserved:

• Full history available
• Edits are tracked
• Deleted comments noted in history
• Audit trail for compliance (Enterprise)

Comments via API

Manage comments programmatically:

# List comments on a file
curl -X GET "https://api.contextium.io/files/{fileId}/comments" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a comment
curl -X POST "https://api.contextium.io/files/{fileId}/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Great documentation!"}'

See API Documentation for full reference.

Next Steps

• Configure notifications
• Use version control
• Access the API