Reference Documentation — Content Standards

Tier: Reference | Reader phase: Refining & Details

What This Tier Is For

The Reference tier covers the Refining & Details phase of the reader journey. Documents here answer: What exactly does this resource/parameter/setting/change mean? Unlike the Guides tier (which is procedural) and the Concepts & Architectures tier (which is conceptual), Reference documents are looked up rather than read — they are optimized for scanning, precision, and completeness over narrative flow.

Document Types

Type	One-line definition	File
Terraform Reference	Entry point and module reference for the Aviatrix Terraform provider	terraform-reference.md
API Reference	Authentication, conventions, and entry point for the Aviatrix REST API	api-reference.md
Best Practices	Curated, opinionated recommendations for a specific area, with justifications	best-practices.md
Copilot UI Reference	Per-page reference for the Aviatrix CoPilot interface	copilot-ui.md
Release Notices	Per-version records of corrected issues, known issues, and field notices	release-notices.md
FAQ	Curated answers to common questions about a specific feature or topic	faq.md

Cross-Cutting Standards

The following standards apply to all document types in this tier.

Optimized for scanning, not reading

Reference documents are consulted mid-task. Readers are looking for a specific piece of information. Structure documents so readers can find what they need without reading from the top:

Use descriptive H2 and H3 headings
Use tables for field/parameter/issue documentation
Keep prose minimal — tables and code blocks carry most of the information

Completeness over brevity

In reference documentation, an incomplete record is worse than a long one. Document every field, every known issue, every input variable — even if the description is brief. If a field seems self-explanatory, still document it.

Precision in language

Use exact product names, exact field names, exact error text, exact version numbers. Reference documentation is the source of truth — approximation and paraphrase cause confusion.

Frontmatter

All documents require title, description, and keywords in frontmatter.

---
title: "[Precise Reference Title]"
description: "Reference for [subject] — [brief scope statement]."
---

Other reference documents

The six doc types above cover the majority of reference content. When content does not fit any of them but is factual, stable, and lookup-oriented, it may still belong in this tier — but only if a clear reader need exists. Examples of legitimate unlisted reference documents: platform limits and quotas, version compatibility matrices, performance benchmarks, glossaries, error code references. Before creating an unlisted reference document, answer two questions: Who is the reader, and what specific question does this answer for them? If you cannot answer both clearly, the content likely belongs as a section within an existing document rather than a standalone page. Unlisted reference documents follow the same cross-cutting standards as the defined types: scannable structure, precise language, complete coverage, and full frontmatter.

What does NOT belong in this tier

Content	Where it belongs
Step-by-step configuration procedures	Configuration Guides (Guides tier)
Upgrade or troubleshooting procedures	Operational Guides (Guides tier)
Architecture design patterns and trade-offs	Architecture docs (Concepts & Architectures tier)
Business cases and ROI	Solutions (Concepts & Architectures tier)

​Reference Documentation — Content Standards

​What This Tier Is For

​Document Types

​Cross-Cutting Standards

​Optimized for scanning, not reading

​Completeness over brevity

​Precision in language

​Frontmatter

​Other reference documents

​What does NOT belong in this tier