--- name: faq_page_builder description: Build FAQ pages from real customer questions: mine support tickets, chat and sales notes for questions, rank and group them by intent, write short self-contained answers in customer language, ship accessible HTML plus valid FAQPage JSON-LD, and keep answers current on a review cycle. Use when creating, rewriting, auditing, or maintaining an FAQ page or FAQ section, adding FAQ schema, or cutting repeat support questions. --- # FAQ Page Builder ## Purpose Turn questions customers actually ask into a page that answers them without a support ticket. The work is mining first, writing second, markup last. A page built from guessed questions looks complete and helps nobody. Read `references/mining-and-freshness.md` for the mining method and review cycle, and `references/schema-and-accessibility.md` before shipping markup or an accordion. ## Workflow ### 1. Mine real questions, do not invent them Pull the last 90 days from every place questions land: support tickets, live chat transcripts, sales call notes, site search terms with no result, and reviews that ask something. Keep the customer's exact wording. Run the miner on a text file (one question per line) or a CSV with `question,count,category`: ``` python3 bin/faq_build.py mine questions.csv --out out/ ``` It normalizes punctuation, groups near-duplicates by shared keywords, keeps the most frequent exact phrasing as the heading, and ranks by count in `out/ranked.md`. Treat the ranking as evidence. A question asked twice a week belongs. A question nobody asked does not, however clever it sounds. No data yet (new product): say so, then seed from competitor FAQ pages, forum threads, and search suggestions, and label the page as seeded. Replace seeded questions with mined ones at the first review. ### 2. Cut and group by intent - Keep the page focused. Ten strong questions beat forty weak ones. - Group by what the visitor is trying to do: getting started, billing, account, troubleshooting, policies. Never group by internal team or product org chart. Visitors do not know that structure. - Order groups by volume, and questions inside a group by frequency. - One question, one answer, one place on the site. The same Q&A on five pages helps none of them. ### 3. Write answers that stand alone Format for every answer: direct answer first, brief context second, next step or link last. - Use the customer's phrasing as the question heading, as a full question. "How do I delete my account?" not "Account termination process." - Plain language. Define any term a first-time buyer would not know. - Target 2 to 4 sentences, roughly 50 to 150 words at most. If a correct answer needs more, it is a help article: put the short answer on the FAQ page and link to the article. - Each answer must make sense read alone, with no reference to the section above or the page around it. Search and answer engines lift single Q&A pairs out of context. - No sales copy inside an answer. Answer the question. A relevant link is fine, a pitch is not. - Date-sensitive facts (prices, limits, policies, deadlines) get named in the freshness register in step 6 at the moment you write them. ### 4. Build the page Write the approved Q&A set as JSON, then generate the page, a Markdown version, and the JSON-LD from the same source so the three can never drift apart: ``` python3 bin/faq_build.py build faq-input.json --out out/ ``` Input is a list of objects with `question`, `answer`, and optional `category`. The builder refuses duplicates and warns on answers over 150 words or under 5 words. Page rules: - Visible contact path near the top. The FAQ is a filter, not a wall. Someone whose question is missing needs support in one click. - Add on-page search once the list passes about 15 to 20 questions. - Use an accordion past about 10 questions, an open list below that. Default pattern in the generated HTML is native `details` and `summary`, which works without JavaScript and is keyboard operable by default. If the design needs a custom accordion, follow the W3C button pattern in the reference file exactly. - Every question and answer in the markup must be visible on the page, collapsed in an accordion counts as visible. Never mark up hidden or invented Q&A. ### 5. Add FAQPage schema, with honest expectations Generate the JSON-LD with the builder, then validate it: ``` python3 bin/faq_build.py validate out/faq.jsonld ``` Set expectations plainly with whoever asked: Google restricted FAQ rich results to well-known government and health sites in August 2023 and stopped showing them in May 2026. Valid FAQPage markup is not penalized and other engines and answer systems still parse labelled Q&A, so ship it as machine-readable hygiene, never as a promised traffic win. See the reference file for the required properties and the rules that still matter (one definition per page, one instance per Q&A site-wide, no advertising in answers, FAQPage for site-authored answers and QAPage only for user-submitted Q&A). ### 6. Put the page on a freshness cycle Create a register next to the source JSON: each question, an owner, and a `last_reviewed` date. Review on a fixed cadence, quarterly is a workable default, and immediately when a price, policy, plan, or product behavior changes. ``` python3 bin/faq_build.py freshness faq-meta.json --max-days 90 ``` At each review: re-mine the last 90 days, promote new frequent questions, retire questions nobody asks anymore, re-check every date-sensitive answer against the current product, and update `last_reviewed` only for answers actually re-verified, not skimmed. ## Output Contract Deliver all of these from one source file: - The ranked question list with counts, so the choices are auditable. - `faq.html`: accessible page with visible contact path and the JSON-LD embedded. - `faq.md`: the same Q&A in Markdown for docs, help centers, and review. - `faq.jsonld`: standalone FAQPage block that validates clean. - The freshness register with owner and last reviewed date per question. - A short note stating which questions were mined, which were seeded, and when the next review is due. ## Operating Rules - Never invent numbers, dates, quotes, or events. Every factual claim in an answer comes from a primary source: product docs, policy pages, or the business itself. Unverifiable means cut it or reframe it as a next step ("check your plan page for current pricing") rather than stating a figure. - Questions come from data. If there is no data, label the set as seeded and schedule its replacement. - Visible text and schema text must match word for word in substance. Drift between them is a defect, fix the source JSON and rebuild. - One canonical home per Q&A. Link to it from product pages instead of copying it. - Accessibility is not a polish step: heading order, keyboard operation, `aria-expanded` state, and visible focus ship with the first version. - Do not promise a Google rich result from FAQ markup. That feature is gone for ordinary sites.