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

# 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:

**All Feedback**

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)
  **By Page**

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.
  **Trends**

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:

```
Score = (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:

**Zero-feedback pages**

Pages with no feedback may have low traffic or a broken widget. Investigate whether the page is reachable and linked from navigation.
  **High-traffic, low-score pages**

Your most impactful improvement targets. Small quality improvements here affect the most readers.
  **Negative comments with patterns**

When multiple readers mention the same issue (outdated code, missing steps, confusing language), prioritize a rewrite.
  **Score drops after changes**

A sudden score decline after a deployment may indicate a regression. Compare the deployment diff with the feedback timeline.

## 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 Service
feedback: false
---
```

To disable feedback site-wide, toggle off the **Feedback widget** feature flag in **Settings > Advanced**.

### Pages Where You Might Disable Feedback

**Legal and policy pages**

Terms of service, privacy policy, and similar pages are not documentation in the traditional sense. Feedback on these pages is rarely actionable.
  **Auto-generated API pages**

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.
  **Changelog and roadmap pages**

These pages serve a different purpose than documentation. Feedback like "this wasn't helpful" on a changelog entry is typically not meaningful.
  **Landing and marketing pages**

If your docs site includes marketing-style landing pages, the "Was this helpful?" widget may feel out of place. Disable it on these pages.

## Next Steps

**[Analytics](/analytics)**

See the full analytics dashboard including page views, search, and AI metrics.
  **[Webhooks](/webhooks)**

Configure webhooks for feedback and other project events.