---
name: faq
description: Build and maintain an FAQ from real, recurring questions — answer-first, searchable, and kept current.
category: docs
---

# FAQ

Use when the same questions keep landing in support, issues, or chat — an FAQ deflects them, but only if it's sourced from real questions, not invented ones.

1. Mine sources: support tickets, issue tracker, chat threads, PR comments. Collect the actual wording people use.
2. Cluster duplicates and rank by frequency × pain; write the top items first, drop the long tail.
3. Phrase each question the way a user would search it ("Why is my build slow?"), not in internal jargon.
4. Answer-first: lead with the direct answer in 1-2 sentences, then optional detail and a link to the full doc.
5. Group into sections (Setup, Billing, Errors…) and add anchor links so answers are shareable.
6. Add a "last reviewed" date and a feedback path ("still stuck? open an issue").
7. Revisit quarterly: promote new recurring questions, delete ones that no longer apply, fix answers that drifted.

## Rules
- Source from real questions only — a guessed FAQ answers nothing anyone asked.
- One question per entry, in the user's words, not the team's.
- Lead with the answer; don't make readers scroll through context to find it.
- Link to canonical docs instead of duplicating them — duplicated answers rot out of sync.
- Prune ruthlessly; a bloated FAQ is as useless as none.