Feedback Widget Configuration

Configuration for the "Was this helpful?" feedback widget shown at the bottom of each documentation page.

---

Widget Overview

Each documentation page displays a feedback bar with:

• Label: "Was this helpful?"
• Options: 👍 Yes | 👎 No
• Optional: Free-text comment field (shown after clicking No)

---

Backend Options

Option 1: Cloudflare Workers KV (Recommended for Production)

Use a Cloudflare Worker to receive feedback and store it in Workers KV.

Architecture:

User clicks feedback → POST /api/feedback → Cloudflare Worker → Workers KV

KV Schema:

{
  "key": "feedback:{page_path}:{timestamp}",
  "value": {
    "page": "/docs/features/document-upload",
    "helpful": true,
    "comment": "",
    "timestamp": "2026-03-25T10:30:00Z",
    "user_agent": "..."
  }
}

Worker endpoint: https://docs.smartflow.io/api/feedback

Rate limiting: Max 5 feedback submissions per page per session.

Option 2: GitHub Issues (Recommended for MVP)

Each feedback submission creates a GitHub Issue in the smartflow-docs repository.

Configuration:

1. Create a GitHub App or Personal Access Token with issues:write scope.
2. Configure the feedback widget to POST to a proxy endpoint.
3. The proxy creates an issue with:
   • Title: Feedback: {page_path} — {helpful ? "Positive" : "Negative"}
   • Labels: feedback, docs
   • Body: Page URL, feedback type, optional comment, timestamp.

---

Review Cadence

Frequency	Action	Owner
Weekly	Review new feedback submissions, triage negative feedback	Product
Monthly	Aggregate feedback metrics per section, identify low-rated pages	Product
Quarterly	Publish feedback summary, prioritize doc improvements	Product + Tech Writing

---

Metrics to Track

Metric	Description	Target
Helpful rate	% of "Yes" clicks per page	> 80%
Feedback volume	Total submissions per week	Trending up (indicates engagement)
Negative feedback with comments	Actionable improvement signals	< 10% of total
Pages with no feedback	Low-traffic or undiscoverable pages	Investigate if critical pages

---

CSS Styles

Feedback widget styles are defined in site/src/css/custom.css under the .feedback-widget class.