Doc Type: Best Practices
Tier: Reference | Reader phase: Refining & Details
Back to tier overview: reference/index.md
What it is
A Best Practices document provides curated, opinionated recommendations for designing, configuring, or operating a specific area of the Aviatrix platform. It tells the reader not just what to do, but why — and it does so from the perspective of accumulated real-world experience. Best Practices docs sit at the boundary between conceptual and procedural content. They contain more “why” than a Configuration Guide, but more “what to do” than an Architecture doc. They are the right place for recommendations that don’t fit cleanly into a single configuration procedure but are too specific and actionable to belong in conceptual documentation. They are not step-by-step configuration guides (those belong in Configuration Guides) and not design patterns (those belong in Architecture docs). They answer: Given that I have this running, what should I do to make it more secure, resilient, or efficient?Goal
After reading a Best Practices document, the reader can assess their current environment against proven recommendations and knows which improvements to prioritize. They leave with specific, justified actions they can take — not a vague sense that things could be better.Primary personas
When to create a new Best Practices document
Create a new Best Practices document when:- There is a set of 5 or more related recommendations for a specific area that cannot be captured in a single Configuration Guide
- The recommendations are based on production experience and not just product documentation
- The recommendations involve trade-offs that require explanation, not just a list of settings to apply
- A single recommendation — add it as a
<Tip>in the relevant Configuration Guide - Pure conceptual content — that belongs in Architecture docs
- Step-by-step configuration — link to the relevant Configuration Guide instead
Required sections
- Overview — 3–5 sentences: what area this covers, what the reader will gain, and any prerequisite knowledge or configuration assumed. Include a brief note on how to use the document (e.g., “Each recommendation is numbered and independent — apply those that match your environment”).
- Best Practice sections — Organized by theme (H2) with individual recommendations as H3 or numbered items. Each recommendation must include:
- What to do (specific and actionable)
- Why it matters (consequence of not following it, or benefit of following it)
- A link to the Configuration Guide or Reference doc that implements it (do not duplicate configuration steps)
- Related Resources — Links to Architecture docs that provide design context, Configuration Guides that implement the recommendations, and Validated Designs that demonstrate them in production.
Optional sections
- Glossary — When the document introduces or relies on terms that are not defined elsewhere
- Compatibility Notes — When recommendations differ by cloud provider, Aviatrix version, or deployment type
- Assessment Checklist — A condensed checklist version of the recommendations, useful for reviews and audits
Tone & voice
Advisory and principled. The reader is experienced — they have the product running and are looking to do it better. Write with authority. Give the reason for every recommendation. Avoid both the instructional tone of a Configuration Guide (“click here”) and the strategic tone of a Solution (“the business case for…”). The best analogy is advice from a trusted expert: direct, specific, and justified. Where a recommendation is context-dependent (not universally applicable), say so explicitly: “If your environment requires X, then Y. If Z applies instead, consider…”Length guidance
200–500 lines. Best Practices documents are reference documents that readers scan rather than read cover-to-cover. Good heading structure is more important than brevity. If a document exceeds 500 lines, consider splitting by theme (e.g., separate Security Best Practices from Resiliency Best Practices).Frontmatter
See Frontmatter Standards for field definitions and formatting rules. Name the title after the area of focus. Format:[Area] Best Practices or Best Practices for [Area]. Example: Network Resiliency Best Practices.
Mintlify components
See Style Guide for component definitions and usage rules. Use<Warning> for recommendations whose absence has serious security or stability consequences, <Note> for conditional or context-dependent recommendations, and tables for comparing options or compatibility matrices.
Linking
- Link in from: No fixed upstream relationship — can be linked from any document where the recommendations are relevant
- Link out to: None — Best Practices documents are standalone reference material