A curated set of questions consumers actually ask, with concise authoritative answers. A good FAQ short-circuits the common-question slice of support load, makes the API feel approachable, and surfaces issues the rest of the documentation does not address head-on. FAQs work best when they are sourced from real support conversations and revised on a cadence rather than written once and abandoned. The honest caveat is that most FAQs are not curated at all — they are where questions get dumped when no one owns the place the answer belongs, which is why a growing FAQ is usually a signal that the reference, the getting-started guide, or the error documentation has a gap. Treat every entry as a candidate for promotion into the docs proper, and measure the FAQ by how few entries it needs rather than how many it has.

Also known as: Frequently Asked Questions, Q&A, Help

Example

- type: FAQ
  url: https://developers.example.com/faq

Standards

• Schema.org schema.org FAQPage
• Schema.org schema.org Question
• Schema.org schema.org Answer
• CommonMark CommonMark 0.31

Link Relations

• help — IANA Link Relations

Risk & Compliance

Security: FAQ entries about authentication and key handling routinely become quoted in support tickets — incorrect or out-of-date guidance there propagates widely. Review the auth/security FAQ entries every spec revision and on every credential-handling change.

Tools

• Algolia DocSearch — Search across FAQ and docs
• Discourse — Community FAQ surfacing (GPL-2.0)
• Mintlify — Docs platform with FAQ components

Suggested Metrics

• faq_search_hit_rate — Share of in-docs search queries that match an FAQ entry — measures coverage.
• ticket_deflection_rate — Drop in support tickets after publishing or updating an FAQ entry.
• faq_freshness_days — Days since each FAQ entry was last reviewed against current product behavior.
• faq_entries_promotable — Count of entries whose answer belongs in the reference, getting-started guide, or error documentation instead — the FAQ's own backlog.
• faq_entry_provenance — Share of entries traceable to a real support ticket or forum thread rather than an internally imagined question.

Example Implementations

• Stripe — Searchable help center with FAQ-style entries linked from product surfaces.
• Plaid — Dedicated developer FAQ alongside reference docs.
• SendGrid — FAQ entries surfaced inline with deliverability and onboarding topics.

Further Reading

• FAQs are not the answer — Fabrizio Ferri Benedetti
  An honest look at why FAQs accumulate — not an anti-pattern so much as content with no strategy around it, unable to grow because it lacks structure and specialization. Its conclusion is worth taking literally - to build a good FAQ, don't build an FAQ.

Related Properties

• Documentation
• Support
• Getting started
• Forums

Tags

• Onboarding
• Support
• Documentation

All Common Properties