Add 'Was this helpful?' feedback on documentation pages

[michaeldistel]

Problem

No way to know if documentation is helpful:

• Can't measure doc quality
• Don't know what needs improvement
• Missing user feedback loop

Solution

Add simple thumbs up/down feedback:

<!-- src/lib/components/DocFeedback.svelte -->
<script lang="ts">
  import { page } from '$app/stores';
  
  let feedback: 'yes' | 'no' | null = null;
  let submitted = false;
  
  async function sendFeedback(helpful: boolean) {
    feedback = helpful ? 'yes' : 'no';
    
    // Send to analytics
    if (typeof gtag !== 'undefined') {
      gtag('event', 'doc_feedback', {
        helpful,
        page: $page.url.pathname,
        timestamp: new Date().toISOString()
      });
    }
    
    // Optionally send to backend
    await fetch('/api/feedback', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        helpful,
        page: $page.url.pathname,
        timestamp: new Date().toISOString()
      })
    });
    
    submitted = true;
  }
</script>

<div class="doc-feedback">
  {#if !submitted}
    <p>Was this page helpful?</p>
    <div class="buttons">
      <button 
        on:click={() => sendFeedback(true)}
        aria-label="Yes, this was helpful"
      >
        👍 Yes
      </button>
      <button 
        on:click={() => sendFeedback(false)}
        aria-label="No, this was not helpful"
      >
        👎 No
      </button>
    </div>
  {:else}
    <p class="thanks">
      {feedback === 'yes' 
        ? '✓ Thanks for your feedback!' 
        : 'Thanks! We\'ll work on improving this page.'}
    </p>
    
    {#if feedback === 'no'}
      <a href="https://github.com/ControlForge-Systems/issues">
        Report an issue →
      </a>
    {/if}
  {/if}
</div>

<style>
  .doc-feedback {
    margin-top: 3rem;
    padding-top: 2rem;
    border-top: 1px solid var(--border);
    text-align: center;
  }
  
  .buttons {
    display: flex;
    gap: 1rem;
    justify-content: center;
  }
  
  button {
    padding: 0.5rem 1.5rem;
    border: 1px solid var(--border);
    border-radius: 4px;
    background: white;
    cursor: pointer;
  }
  
  button:hover {
    background: var(--bg-hover);
  }
</style>

Enhanced Version with Comments

If user clicks "No", show optional comment field:

{#if feedback === 'no' && !submitted}
  <div class="comment-box">
    <label for="feedback-comment">
      What could we improve? (optional)
    </label>
    <textarea 
      id="feedback-comment"
      bind:value={comment}
      placeholder="Tell us what's missing or unclear..."
    />
    <button on:click={submitWithComment}>
      Submit
    </button>
  </div>
{/if}

Data Storage Options

Option 1: Google Analytics (Simple)

gtag('event', 'doc_feedback', {
  helpful: true,
  page: '/docs/syntax'
});

Option 2: SvelteKit Endpoint (Better)

// src/routes/api/feedback/+server.ts
export async function POST({ request }) {
  const data = await request.json();
  
  // Store in database, CSV, or send to service
  await logFeedback(data);
  
  return new Response(JSON.stringify({ success: true }));
}

Option 3: GitHub Issues (Advanced)

Auto-create GitHub issue if feedback is negative

Analytics

Track metrics:

• Helpfulness score per page
• Pages with low scores (need improvement)
• Total feedback count
• Comment themes

Success Criteria

• Feedback widget on all doc pages
• Data tracked in GA or backend
• Thank you message shown after submission
• Link to GitHub issues if negative
• Mobile responsive