Skip to main content

​
customer-docs Style Guide

This file defines conventions for content in customer-docs/. It is internal — Mintlify only publishes pages listed in docs.json navigation, so this file does not ship. See also: QUALITY-AUDIT.md (historical audit scoring log, separate artifact).

​
Q&A Sections

​
Required component

Every Q&A section uses the <FAQ> / <FAQItem> component from /snippets/FAQ.jsx: 
import { FAQ, FAQItem } from '/snippets/FAQ.jsx'

<FAQ>
  <FAQItem question="How do I rotate my API key?">
    Go to Settings, API Keys, and click **Rotate**. The old key keeps working for 24 hours.
  </FAQItem>
  <FAQItem question="What happens to running jobs when I rotate?">
    They continue on the old key until it expires. New jobs use the new key immediately.
  </FAQItem>
</FAQ>
The import goes at the top of the file, directly below frontmatter. Place the <FAQ> block near the bottom of the page, above any “Related Pages” section.

​
Banned patterns

  • <AccordionGroup> / <Accordion> for Q&A content. The question text lives in a title attribute that renders as a button label, not a heading element. It hurts Google featured-snippet extraction, and build-markdown.js strips it from .md mirrors (making the Q&A invisible to LLMs that fetch the markdown).
  • Raw ### Q? Markdown Q&A blocks. No structured data, no single source of truth. If you need Q&A on a page, use <FAQ>.
  • Empty <FAQ> blocks or placeholder <FAQItem> entries. Ship real answers or skip the section entirely.
Accordions are still fine for non-Q&A content (e.g., long configuration detail that benefits from collapse). The ban is specific to question-answer content.

​
Rubric (per-question gate)

Every <FAQItem> must pass all four tests. A reviewer rejects any Q that fails.
  1. Deletion test (uniqueness): if this page is deleted, does the answer become wrong or missing? If the answer lives equally on three other pages, it belongs on the most canonical one, not here.
  2. Volume test (traffic): do real people search for or ask an LLM this question? Cite at least one seeding source — Google Search Console impressions, “People Also Ask” accordion, Google auto-complete, AnswerThePublic, support ticket, or LLM query log. A Q without a volume source is a red flag in review.
  3. User phrasing, not doc phrasing: the question starts with Who/What/When/Where/Why/How/Is/Does/Can/Should and ends with ?. Good: “How do I rotate my API key?” Bad: “API key rotation.”
  4. Short answers, link out for depth: 2-4 sentences. Answer the question directly, then link to the canonical page or section if the reader needs more. Long explanations go in the prose of the page, not in the Q&A.

​
Per-page Q count

0 to ~6 questions per page. No template, no quota. A reference page listing enum values may have 0 Qs; a concept page on freshness thresholds may have 6. Pages with 0 Qs don’t need justification in code — reviewer notes it in the PR if unclear.

​
Skip List — Pages That Don’t Get Q&A

The governing principle: if a prospect would not organically land on this page from a search result or LLM answer, skip it. These pages cannot drive acquisition traffic, so Q&A work on them is wasted effort. Skip the following:
  • releases/** — release notes / changelog. Version-specific, churns every release.
  • Anything with a version number in the filename or frontmatter.
  • api-reference/** auto-generated endpoint pages — the endpoint spec is the answer.
  • Deep internal reference (API error code tables, low-level config reference).
  • Pure reference tables (enum lists, status code charts) where every row is already a pseudo-answer.
  • Landing / nav pages with no real content (section index pages that are just a list of links).
  • Post-auth / logged-in-only pages — user settings, admin config, billing management that only existing authenticated users can reach. Apply per-page, not per-folder: security/, billing/, and account/ each contain prospect-facing pages that are still in scope.
  • App-only pages — anything only reachable from inside the product UI (in-app help flyouts, admin panels, internal tools surfaced as docs). If the URL isn’t indexed by Google and isn’t quoted by LLMs, it’s out of scope here.

​
Toolchain

When you add or edit <FAQ> content:
  1. Run node customer-docs/build-markdown.js locally. This regenerates the .md mirror for the page via the FAQ conversion rule (see build-markdown.js, conversions.faq).
  2. Confirm the Q&A content appears in the regenerated .md file. If it doesn’t, the toolchain regressed — investigate before merging.
  3. Optionally run node customer-docs/scripts/generate-llms-txt.js to update llms.txt (typically unchanged since it only reads frontmatter descriptions).
The FAQ component renders to plain <h2> / <h3> HTML in the live Mintlify page plus a <script type="application/ld+json"> FAQPage block for Google structured data. Everything comes from a single source: the <FAQItem question="..."/> props and children.

​
References

  • /snippets/FAQ.jsx — the FAQ / FAQItem component implementation.
  • build-markdown.js — Node build-time script that generates .md mirrors. The conversions.faq rule (patterned on conversions.tabs) handles <FAQ> → H2 + H3 Q&A markdown.
  • mdx-to-markdown.js — browser-side script that converts the live rendered DOM to markdown for copy-as-markdown. No FAQ-specific handling needed; the component’s plain HTML output flows through the generic HTML-to-Markdown converter.
  • docs/tasks/backlog/TECH-980-customer-docs-qa-backfill.md — the full PRD behind this convention.