Skip to main content

​
Doc Type: FAQ

Tier: Reference | Reader phase: Refining & Details
Back to tier overview: reference/index.md

​
What it is

An FAQ document is a curated set of questions and answers for a specific Aviatrix feature, component, or topic area. FAQs serve readers who arrive with a specific question and need a direct, targeted answer — they are optimized for scanning, not reading. FAQs are reference documents. They are consulted mid-task or mid-evaluation, not read from start to finish. Every answer should be self-contained: a reader who jumps to a specific question should get a complete, useful answer without needing to read the surrounding questions.

​
Goal

After reading an FAQ document, the reader has a direct, specific answer to their question. They do not need to read the entire document — they find their question, get a complete answer, and know where to go for more depth if needed.

​
Primary personas

​
When to create an FAQ

Create an FAQ document when:
  • There are 5 or more distinct, commonly asked questions about a specific topic that do not fit neatly into existing Component, Configuration Guide, or Best Practices documents
  • The questions come from real sources: support tickets, sales calls, field engineer conversations, community forums
  • The answers are factual and stable — not highly version-dependent
Before creating an FAQ, ask whether the content belongs elsewhere: FAQs are not a dumping ground for content that hasn’t found a home yet. If a question would be better answered by improving an existing document, improve the document rather than adding an FAQ entry.

​
What questions to include

Include a question when:
  • It has been asked by multiple independent customers, prospects, or engineers
  • The answer is not immediately obvious from the product interface or existing docs
  • The answer is stable enough to be documented (not “it depends on your specific setup” with no further guidance)
Do not include:
  • Questions you invented to seem thorough — every FAQ entry should have a real origin
  • Questions whose answers are “read the [X] doc” — link to the doc instead
  • Questions that require a multi-page answer — that content belongs in a proper doc type

​
Required sections

  1. Overview — 1–2 sentences identifying what topic this FAQ covers and who it is for. This is the only prose section; everything else is Q&A.
  2. Question sections — Organize questions into H2 thematic groups (e.g., “Licensing”, “Performance”, “Troubleshooting”). Each question is an H3. The answer follows directly in paragraph form below the H3 heading.

​
Format

Each question is an H3 heading phrased as a direct question in second person. The answer is the content beneath it.
Answer length: Keep answers to 3–6 sentences. If an answer requires more, the question probably belongs in a dedicated document. Link to that document from the FAQ answer rather than expanding the answer.

​
Tone & voice

Direct and factual. FAQ readers want an answer, not a preamble. Start the answer with the answer — not with “Great question” or “This depends on many factors.” If an answer genuinely depends on conditions, state what it depends on immediately.

​
Length guidance

Length is determined entirely by the number of questions — there is no target. A FAQ with fewer than 5 questions is probably not worth a standalone page; consider whether those answers belong inline in an existing document instead. Each individual answer should be 3–6 sentences. If an answer grows beyond that, the question likely belongs in a dedicated document.

​
Frontmatter

See Frontmatter Standards for required fields and formatting rules. FAQ-specific guidance:
  • title: [Topic Area] FAQ. Example: Distributed Cloud Firewall FAQ.
  • description: State the topic and who the FAQ is for. Example: "Answers to common questions about Aviatrix Distributed Cloud Firewall — covering licensing, performance, rule behavior, and troubleshooting."
  • keywords: Include the topic area, common question terms, and any alternative names for the feature.

​
Mintlify components

See Style Guide for component definitions and usage rules. FAQ-specific notes:
  • Use <Note> or <Warning> callouts within answers when a constraint or risk needs to stand out
  • Do not use <Steps>, <Tabs>, or <CardGroup> — FAQ answers should be concise prose
  • Code blocks are appropriate for CLI commands, API snippets, or configuration values referenced in an answer

​
Linking

  • Link in from: No fixed upstream relationship — can be linked from any document where the FAQ is relevant
  • Link out to: None — FAQ documents are endpoint destinations

​
Dos and don’ts