Skip to content

DOCUMENTATION_FEEDBACK_MECHANISMS.md

Latest commit

 

History

History
537 lines (398 loc) · 13 KB

DOCUMENTATION_FEEDBACK_MECHANISMS.md

File metadata and controls

537 lines (398 loc) · 13 KB

Documentation Feedback Mechanisms

Version: 1.0
Last Updated: 2026-04-06
Status: Official

Overview

This document describes the various mechanisms for collecting, tracking, and responding to feedback on ThemisDB documentation. Effective feedback collection ensures documentation continuously improves based on user needs.

Feedback Channels

1. GitHub Issues

Primary channel for documentation feedback

How to submit:

# Using GitHub CLI
gh issue create --label docs --title "docs: [Brief description]"

# Or via web interface
# Navigate to: https://github.com/makr-code/ThemisDB/issues/new

Issue template for documentation:

---
name: Documentation Issue
about: Report problems or suggest improvements to documentation
title: 'docs: [Brief description]'
labels: docs
assignees: ''
---

## Documentation Issue

**Affected Page/Section:**
- URL or file path: 
- Section/heading: 

**Issue Type:**
- [ ] Incorrect information
- [ ] Missing information
- [ ] Unclear/confusing
- [ ] Broken link
- [ ] Outdated content
- [ ] Typo/grammar
- [ ] Other: 

**Description:**
<!-- Describe the issue clearly -->

**Expected:**
<!-- What you expected to find -->

**Actual:**
<!-- What you actually found -->

**Suggested Fix:**
<!-- Optional: How to improve this -->

**Additional Context:**
<!-- Screenshots, examples, etc. -->

**Environment:**
- ThemisDB version: 
- Documentation version: 
- Browser (if relevant):

Labels for documentation issues:

  • docs - General documentation
  • docs/api - API documentation
  • docs/examples - Example code
  • docs/guide - User guides
  • docs/translation - Translation issues
  • good first issue - Easy fixes for new contributors

2. Pull Requests

Direct contributions to documentation

How to contribute:

# 1. Fork repository
gh repo fork makr-code/ThemisDB

# 2. Create branch
git checkout -b docs/improve-feature-guide

# 3. Make changes
vim docs/features/my-feature.md

# 4. Commit
git add docs/
git commit -m "docs: Improve feature X guide"

# 5. Push and create PR
git push origin docs/improve-feature-guide
gh pr create --label docs

PR template includes documentation checklist:

3. GitHub Discussions

For questions, suggestions, and general feedback

Categories:

  • Q&A: Ask questions about documentation
  • Ideas: Suggest documentation improvements
  • Show and Tell: Share your usage examples
  • General: Other documentation discussions

How to participate:

# Start a discussion
gh discussion create \
  --category "Ideas" \
  --title "Suggestion: Add more API examples" \
  --body "It would be helpful to have..."

# Or via web interface
# Navigate to: https://github.com/makr-code/ThemisDB/discussions

4. Inline Documentation Feedback

Future enhancement: In-page feedback buttons

Planned for documentation website:

  • "Was this helpful?" (Yes/No)
  • "Report an issue" button
  • "Suggest an edit" button
  • Comments section (optional)

5. Support Channels

Community Support:

  • Discord/Slack (if available)
  • Mailing list (if available)
  • Stack Overflow: Tag themisdb

Common documentation-related questions should be:

  1. Answered immediately
  2. Documented in FAQ
  3. Used to improve documentation

6. Internal Feedback

From developers and maintainers:

  • Code review comments
  • Planning meeting discussions
  • Retrospective feedback
  • Direct communication

Process:

  1. Document feedback in issue tracker
  2. Prioritize in planning
  3. Assign to appropriate person
  4. Track in documentation board

Feedback Triage

Priority Levels

Priority Response Time Examples
P0 - Critical <24 hours Incorrect security info, broken installation guide
P1 - High <7 days Major errors, API docs wrong, broken examples
P2 - Medium <30 days Unclear sections, missing examples, minor errors
P3 - Low <90 days Typos, formatting, nice-to-have improvements

Triage Process

When feedback is received:

  1. Acknowledge (within 24 hours)

    Thank you for reporting this! We'll review and address it.

  2. Assess (within 48 hours)

    • Verify the issue
    • Determine priority
    • Assign labels
    • Assign to owner

  3. Respond (based on priority)

    • Explain what will be done
    • Provide workaround if available
    • Set expectations for timeline

  4. Track (ongoing)

    • Update issue with progress
    • Link to related PRs
    • Close when resolved

Triage Checklist

## Feedback Triage Checklist

**Issue:** #XXX  
**Triaged By:** @username  
**Date:** YYYY-MM-DD

### Assessment
- [ ] Issue verified and reproducible
- [ ] Affected documentation identified
- [ ] Impact assessed

### Classification
- **Type:** Incorrect / Missing / Unclear / Other
- **Scope:** Page / Section / Example / API
- **Priority:** P0 / P1 / P2 / P3
- **Effort:** Small (<1h) / Medium (1-4h) / Large (>4h)

### Labels Applied
- [ ] `docs`
- [ ] Specific area (api/guide/examples/etc.)
- [ ] Priority label
- [ ] Type label (bug/enhancement)
- [ ] `good first issue` (if applicable)

### Assignment
- **Assigned To:** @username
- **Milestone:** vX.Y.Z
- **Due Date:** YYYY-MM-DD (based on priority)

### Response
- [ ] Initial response sent
- [ ] Workaround provided (if applicable)
- [ ] Timeline communicated

### Notes
<!-- Additional context or considerations -->

Response Templates

For Reporting Issues

Thank you - Will fix:

Thank you for reporting this issue! You're absolutely right that [describe issue].

We'll fix this in the next documentation update. I've assigned it to @owner 
and set priority to [priority] with an estimated resolution by [date].

In the meantime, [workaround if available].

I'll update this issue when the fix is merged.

Thank you - Already fixed:

Thank you for reporting this! This issue was actually fixed in [version/PR].

The updated documentation is available at [link].

If you're still seeing the old version, please clear your browser cache or 
check that you're viewing the latest documentation at [link].

Closing this as resolved. Please reopen if the issue persists.

Thank you - Working as intended:

Thank you for the feedback! After reviewing, the current documentation is 
actually correct because [explanation].

However, I understand why this might be confusing. We'll improve the clarity 
by [proposed improvement]. Created issue #XXX to track this.

Does this explanation help clarify? Let us know if you have further questions.

Thank you - Need more information:

Thank you for reporting this! To help us address this issue, could you provide:
- Which version of ThemisDB you're using?
- The exact page/section where you found this?
- What you expected vs what you found?
- [Other specific questions]

This will help us identify and fix the issue more quickly.

For Suggesting Improvements

Good suggestion - Will implement:

Great suggestion! This would definitely improve the documentation.

I've created issue #XXX to track this work and assigned it to @owner.
We're targeting [milestone] for implementation.

If you'd like to contribute this yourself, we'd welcome a PR! 
Check out our [Contributing Guide](../CONTRIBUTING.md).

Good suggestion - Future consideration:

Thank you for the suggestion! This is a good idea that we'll consider 
for future improvements.

I've added it to our documentation improvement backlog as issue #XXX 
with priority P3. While we can't commit to a specific timeline, we'll 
revisit this in our quarterly documentation reviews.

Would you be interested in contributing this yourself? We welcome PRs!

For Questions

Answered in documentation:

Thanks for your question! This is covered in [documentation link]:

[Quote relevant section or provide summary]

If this doesn't fully answer your question, or if the documentation 
could be clearer, please let us know and we'll improve it!

Not documented - Will add:

Great question! This isn't currently documented, but it should be.

Here's the answer: [Provide answer]

I've created issue #XXX to add this to the documentation. Thanks for 
helping us identify this gap!

Tracking and Metrics

Metrics to Track

Volume Metrics:

  • Documentation issues opened per month
  • Documentation PRs submitted per month
  • Questions asked per channel
  • Average response time
  • Average resolution time

Quality Metrics:

  • Feedback sentiment (positive/negative)
  • Documentation clarity score (from feedback)
  • Issue recurrence rate
  • User satisfaction (surveys)

Process Metrics:

  • % issues triaged within 48h
  • % P0/P1 issues resolved within SLA
  • % issues resolved by community
  • % feedback resulting in improvements

Monthly Feedback Report Template

# Documentation Feedback Report - [Month YYYY]

**Report Date:** YYYY-MM-DD  
**Reporting Period:** [Start Date] to [End Date]

## Summary

### Volume
- **Issues Opened:** XX
- **PRs Submitted:** XX
- **Discussions Started:** XX
- **Total Feedback Items:** XX

**Trend:** ↑/↓/→ XX% from last month

### Response Performance
- **Average Response Time:** XX hours
- **Average Resolution Time:** XX days
- **Within SLA:** XX%

## Breakdown by Type

| Type | Count | % of Total | Top Issues |
|------|-------|------------|------------|
| Incorrect | XX | XX% | Issue #XXX, #YYY |
| Missing | XX | XX% | Issue #XXX, #YYY |
| Unclear | XX | XX% | Issue #XXX, #YYY |
| Examples | XX | XX% | Issue #XXX, #YYY |
| Typo/Grammar | XX | XX% | - |

## Breakdown by Priority

| Priority | Opened | Resolved | Open | Avg Resolution Time |
|----------|--------|----------|------|---------------------|
| P0 | X | X | X | XX hours |
| P1 | X | X | X | XX days |
| P2 | X | X | X | XX days |
| P3 | X | X | X | XX days |

## Top Issues This Month

1. **Issue #XXX** - [Title] (P1, XX comments)
   - Status: Resolved
   - Impact: High
   - Resolution: [Brief description]

2. **Issue #YYY** - [Title] (P1, XX comments)
   - Status: In Progress
   - Impact: High
   - ETA: YYYY-MM-DD

3. **Issue #ZZZ** - [Title] (P2, XX comments)
   - Status: Open
   - Impact: Medium
   - Plan: [Brief description]

## Community Contributions

- **Contributors:** XX users
- **PRs Merged:** XX
- **New Contributors:** XX

**Notable Contributions:**
- @user1: Improved API documentation
- @user2: Added examples for feature X
- @user3: Fixed broken links

## Trends and Insights

### Common Themes
1. Theme 1: [Description]
2. Theme 2: [Description]
3. Theme 3: [Description]

### Documentation Gaps Identified
1. Gap 1: [Description] → Issue #XXX
2. Gap 2: [Description] → Issue #YYY

### User Pain Points
1. Pain point 1: [Description]
2. Pain point 2: [Description]

## Actions Taken

### Improvements Made
- Improvement 1: [Description]
- Improvement 2: [Description]
- Improvement 3: [Description]

### Issues Resolved
- XX issues resolved this month
- Top resolved: #XXX, #YYY, #ZZZ

### New Issues Created
- Issue #AAA - [Brief description]
- Issue #BBB - [Brief description]

## Action Items for Next Month

### High Priority
- [ ] Address issue #XXX (P1)
- [ ] Implement improvement #YYY (P1)

### Process Improvements
- [ ] Improvement 1
- [ ] Improvement 2

### Upcoming Focus
- Area 1: [Description]
- Area 2: [Description]

## Appendix: All Feedback Items

### Issues
| # | Title | Priority | Status | Age |
|---|-------|----------|--------|-----|
| #XXX | Title | P1 | Open | XX days |
| #YYY | Title | P2 | Resolved | XX days |
...

### PRs
| # | Title | Status | Author | Merged Date |
|---|-------|--------|--------|-------------|
| #XXX | Title | Merged | @user1 | YYYY-MM-DD |
| #YYY | Title | Open | @user2 | - |
...

### Discussions
| Title | Category | Replies | Status |
|-------|----------|---------|--------|
| Discussion 1 | Ideas | XX | Active |
| Discussion 2 | Q&A | XX | Resolved |
...

Continuous Improvement

Feedback on Feedback Process

We welcome feedback on our feedback process!

How to provide:

  • Open an issue: "meta: Feedback on documentation feedback process"
  • Start a discussion in "General" category
  • Contact documentation owner directly

Process Reviews

Quarterly Review:

  • Analyze feedback metrics
  • Identify process improvements
  • Update feedback mechanisms
  • Improve response templates

Questions to ask:

  • Are we responding fast enough?
  • Are we resolving issues effectively?
  • Are we closing the feedback loop?
  • Are we learning from feedback?
  • Can we make feedback easier to provide?

Related Documentation

Questions about feedback? Open an issue or start a discussion!