> ## Documentation Index > Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt > Use this file to discover all available pages before exploring further. # Best practices # Doc Type: Best Practices > **Tier**: Reference | **Reader phase**: Refining & Details\ > **Back to tier overview**: [reference/index.md](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 | Persona | How they use it | | - | - | | **Architect** | Uses for design validation and hardening recommendations | | **Engineer** | Uses for implementation hardening after initial configuration | | **Operator** | Uses for operational hygiene and resilience planning | *** ## 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 Do not create a Best Practices document for: * A single recommendation — add it as a `` 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 1. **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"). 2. **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) 3. **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](../frontmatter.md) 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*. ```yaml theme={null} --- title: "[Area] Best Practices" description: "Recommended practices for [area] in Aviatrix — covering [theme 1], [theme 2], and [theme 3]." --- ``` *** ## Mintlify components See [Style Guide](../style-guide.md) for component definitions and usage rules. Use `` for recommendations whose absence has serious security or stability consequences, `` 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 *** ## Dos and don'ts | Do | Don't | | - | - | | Justify every recommendation with a "why" | List recommendations without explanation | | Link to Configuration Guides rather than duplicating steps | Re-explain configuration procedure — link to the guide | | Note when a recommendation is conditional on environment | Present every recommendation as universally applicable | | Organize by theme with clear H2 headings | Write as a flat numbered list with no structure | | State the consequence of not following the recommendation | Leave readers to infer why something matters | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.