Feedback
Collect and manage reader feedback on your documentation pages.
Overview
HolyDocs includes a built-in feedback system that lets readers tell you whether a page was helpful and, optionally, explain why. Every data point flows into the Feedback dashboard where you can identify underperforming pages, track satisfaction trends, and take action to improve your documentation.
Access feedback data from the Feedback item under the Manage section in your project sidebar.
The Feedback Widget
Every page on your documentation site displays a "Was this page helpful?" widget at the bottom of the content area. The widget presents two options:
- Thumbs up — The page was helpful
- Thumbs down — The page was not helpful
After selecting a rating, an optional text field expands where readers can leave a written comment explaining their experience.
The feedback widget appears automatically on all pages. No configuration is needed to start collecting feedback — it works out of the box as soon as your documentation is deployed.
Widget Behavior
| Interaction | Result |
|---|---|
| Reader clicks thumbs up | Rating is recorded. A "Thank you!" confirmation appears. Optional comment field expands. |
| Reader clicks thumbs down | Rating is recorded. A "Sorry to hear that" message appears with the comment field expanded and focused. |
| Reader submits a comment | Comment is attached to the rating. The widget collapses to a "Feedback received" state. |
| Reader revisits the page | The widget shows their previous rating. They can change it or add a comment. |
How Feedback Is Tracked
Feedback submissions are tied to a privacy-friendly anonymous session identifier. No cookies or personal data are collected. If your documentation has authentication enabled, feedback is tied to the authenticated user instead.
Viewing Feedback in the Dashboard
The Feedback page in the dashboard provides three views:
A chronological list of every feedback submission across all pages. Each row shows:
- Page — The page path and title
- Rating — Thumbs up or thumbs down icon
- Comment — The reader's written feedback (if provided)
- Date — When the feedback was submitted
- Source — Anonymous or authenticated user identifier
Use the filters at the top to narrow by:
- Rating (positive, negative, or all)
- Date range
- Page path (search or select from dropdown)
- Has comment (only show feedback with written comments)
A page-level summary showing satisfaction scores for every page in your documentation:
| Column | Description |
|---|---|
| Page | Page path and title |
| Score | Satisfaction percentage (thumbs up / total ratings) |
| Total ratings | Total number of feedback submissions |
| Comments | Number of written comments |
| Trend | Score change over the last 30 days (arrow up, down, or flat) |
Click any row to see all individual feedback entries for that page.
Sort by any column. The default sort shows pages with the lowest satisfaction score at the top — these are the pages that need the most attention.
Time-series charts showing feedback patterns over your selected date range:
- Overall satisfaction — Line chart of daily/weekly satisfaction percentage
- Feedback volume — Bar chart of submissions per day/week
- Top improved pages — Pages with the biggest positive score change
- Top declined pages — Pages with the biggest negative score change
Feedback Analytics
Satisfaction Score
The satisfaction score is calculated as:
textScore = (Positive ratings / Total ratings) x 100
Scores are computed at the page level, section level (navigation group), and project level. The project-level score gives you a single number that represents overall documentation quality.
Benchmarks
| Score | Interpretation |
|---|---|
| 90-100% | Excellent. Readers find your docs highly useful. |
| 75-89% | Good. Most pages are helpful but some need attention. |
| 50-74% | Needs improvement. Review low-scoring pages and reader comments. |
| Below 50% | Critical. Significant content gaps or quality issues to address. |
Focus on pages with a low satisfaction score and a high number of ratings. A page with a 40% score and 200 ratings is a higher priority than a page with a 30% score and 3 ratings.
Actionable Insights
The feedback dashboard highlights patterns that suggest specific actions:
Responding to Feedback
When a reader leaves a comment, you can respond directly from the dashboard:
Open the feedback entry
Click any feedback row in the All Feedback view to open the detail panel.
Write a response
Type your response in the reply field. Responses are internal by default — visible only to your team in the dashboard.
Mark as resolved
After addressing the feedback (by updating the page, responding, or deciding no action is needed), click Resolve to move the entry to the resolved state. Resolved entries are hidden from the default view but remain accessible via the "Show resolved" filter.
Reader responses are internal notes for your team. Readers do not receive notifications when you respond. If you need to follow up with a reader directly, use the email address available on authenticated feedback submissions.
Webhook Integration
Send feedback events to external services in real time using webhooks. Configure feedback webhooks in Settings > Integrations or via the API.
Webhook Payload
When a feedback event fires, HolyDocs sends a POST request with the following payload:
json{ "event": "feedback.created", "timestamp": "2026-04-11T14:30:00Z", "data": { "id": "fb_abc123", "projectId": "proj_xyz", "pagePath": "/quickstart", "pageTitle": "Quickstart Guide", "rating": "negative", "comment": "The code example on line 3 is outdated.", "userId": null, "sessionId": "anon_def456" }}
Common Webhook Destinations
| Destination | Use Case |
|---|---|
| Slack | Post negative feedback to a #docs-feedback channel for immediate visibility |
| Linear / Jira | Auto-create issues for negative feedback with comments |
| Zapier / Make | Route feedback to any downstream tool via no-code automation |
| Custom endpoint | Send to your own API for custom processing and aggregation |
Set up a Slack webhook for negative feedback with comments. This gives your team immediate visibility into documentation pain points without needing to check the dashboard.
Webhook Events
| Event | Fires When |
|---|---|
feedback.created | A new feedback submission is received |
feedback.updated | A reader changes their rating or adds a comment to an existing submission |
Using Feedback to Improve Documentation
A structured approach to acting on feedback data:
Review weekly
Set a weekly cadence to review the Feedback dashboard. Sort by lowest satisfaction score to identify the pages that need the most attention.
Read the comments
Quantitative scores tell you where the problems are. Written comments tell you what the problems are. Always read the comments on low-scoring pages before making changes.
Update the page
Make targeted improvements based on the feedback. Common fixes: updating outdated code examples, adding missing prerequisites, clarifying ambiguous instructions, and adding screenshots.
Monitor the impact
After deploying changes, watch the satisfaction score for that page over the next 1-2 weeks. A rising score confirms the improvement was effective.
Disabling Feedback on Specific Pages
While the feedback widget is enabled globally by default, you can disable it on individual pages using frontmatter:
mdx---title: Terms of Servicefeedback: false---
To disable feedback site-wide, toggle off the Feedback widget feature flag in Settings > Advanced.
Pages Where You Might Disable Feedback
Terms of service, privacy policy, and similar pages are not documentation in the traditional sense. Feedback on these pages is rarely actionable.
If your API reference is generated from an OpenAPI spec, feedback on individual endpoint pages may not be useful since the content is not hand-authored. Consider disabling feedback on these pages and collecting API feedback through a separate channel.
These pages serve a different purpose than documentation. Feedback like "this wasn't helpful" on a changelog entry is typically not meaningful.
If your docs site includes marketing-style landing pages, the "Was this helpful?" widget may feel out of place. Disable it on these pages.