faq_page_builder v1.0.0

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.