Which Doc Type Should I Use?

Back to overview: Content Standards

Use this page to quickly identify the right document type for your content. Start with the landscape diagram to orient yourself, then use the decision table or the question flow to land on the right type.

The documentation landscape

The diagram below shows all doc types across the three tiers and how they connect. Solid arrows show primary reading paths within a tier. Dashed arrows show cross-tier links. Gray arrows show how content in higher tiers drives readers to lower tiers.

Aviatrix documentation landscape showing three tiers — Concepts & Architectures, Guides, and Reference — and the relationships between document types

Three tiers, three reader phases:

Concepts & Architectures — The reader is in understanding mode. They want to know what Aviatrix does, why it matters, and how to think about designing with it. No configuration steps here.
Guides — The reader is in doing mode. They have a defined task and want to complete it step by step.
Reference — The reader is in looking something up mode. They know what they want and need a precise, scannable answer.

Decision table

Find your content type in the left column, then read across to the recommended doc type.

I want to document…	Doc type	Tier
The strategic vision and framework for the entire platform	CNSF	C&A
Why a class of business problem matters and why Aviatrix is the right answer	Solution	C&A
How to design a system that solves a specific problem using Aviatrix	Architecture	C&A
A specific, tested implementation of an architecture with performance data	Validated Design	C&A
What a specific Aviatrix component or platform capability is and how it works	Component	C&A
How to configure a feature or workflow step by step	Configuration Guide	Guides
How to upgrade, troubleshoot, or maintain Aviatrix in production	Operational Guide	Guides
The Aviatrix Terraform provider or a published module	Terraform Reference	Reference
The Aviatrix REST API	API Reference	Reference
What each field or control on a CoPilot page means	CoPilot UI Reference	Reference
Opinionated recommendations for a specific area, with justifications	Best Practices	Reference
What changed in a specific release, or a field/security notice	Release Notices	Reference
Answers to common questions about a specific feature or topic	FAQ	Reference

Decision flow

If you are unsure which row fits, work through these questions: 1. Does the content contain step-by-step instructions the reader must follow?

Yes → Go to question 2
No → Go to question 4

2. Is the task about initial setup or configuration of a feature?

Yes → Configuration Guide
No → Go to question 3

3. Is the task about upgrading, troubleshooting, or ongoing maintenance?

Yes → Operational Guide
No → Go back and reconsider — most procedural content fits one of these two types

4. Is the content primarily a business case for why a problem matters?

Yes → Solution

5. Is the content a design pattern for how to architect a solution?

Yes → Architecture

6. Is the content explaining what a specific Aviatrix component or capability is and how it works technically?

Yes → Component

7. Is the content a curated set of real questions and direct answers?

Yes → FAQ

8. Is the content a reference table, field list, or precision lookup?

Terraform resources → Terraform Reference
API endpoints → API Reference
CoPilot UI fields → CoPilot UI Reference
Design/operational recommendations with justifications → Best Practices
What changed in a release → Release Notices

9. Does the content cover the entire platform’s strategic framework?

Yes → CNSF (there is only one of these)

10. Is the content a specific deployment that has been validated with real performance data?

Yes → Validated Design

11. Does the content not fit any of the above?

If it is factual, stable, and lookup-oriented — and a reader has a genuine reason to consult it — place it in the Reference tier as an unlisted type (see Reference tier guidance).
If you cannot clearly state the reader need it serves, do not create it. Content that does not fit the taxonomy is usually content that does not yet need to exist as a standalone page. Consider whether it belongs as a section within an existing doc instead.

Procedure granularity: UI Reference vs. Configuration Guide

A common over-engineering pattern is creating a dedicated Configuration Guide for something that is actually a single action. Use this test:

The task is…	Use
A single action on a CoPilot page (Create, Edit, Delete, Enable…)	CoPilot UI Reference — document as an action accordion in the Actions section
A field or control description	CoPilot UI Reference — document in the Fields table
A multi-step workflow involving multiple actions or pages	Configuration Guide — include the steps directly; use snippets to avoid duplicating action definitions that also appear in the UI Reference

Component scope

Component docs are for Aviatrix-specific components and capabilities with their own design model. They are not the right place for industry-standard technologies or sub-feature settings. Industry-standard technologies (BGP, BFD, OSPF, IPsec, TLS, etc.) do not get Component pages. Assume the reader knows the concept — a one-sentence framing in the relevant guide is sufficient. Sub-features and individual settings belong in a Configuration Guide or CoPilot UI Reference, not a Component doc. Enabling BFD on a BGP session is a configuration step, not an Aviatrix component.

Common mistakes

Putting configuration steps in a Component or Architecture doc. Component docs explain what a thing is and how it works — they do not walk through UI steps. Architecture docs describe design decisions — they do not include Terraform snippets. If you find yourself writing numbered steps with UI element names bolded, you are in a Configuration Guide, not a conceptual doc. Writing a FAQ when a Component doc or Troubleshooting Guide should be improved. FAQs are for questions that genuinely don’t fit elsewhere. If a common question is “how does DCF work?”, the answer belongs in the DCF Component doc — not a FAQ entry. Creating a new doc type when an existing one suffices. If your content is conceptual but you feel it doesn’t fit any of the five C&A types, check whether it is actually a Best Practices doc (it has actionable recommendations) or belongs as a section within an existing Component or Architecture doc rather than a standalone page. Writing a Solution when the real need is a Component doc. Solutions make the business case for a class of problem. If you are explaining what a feature does — even with a business framing — that content belongs in a Component doc, not a Solution.

​Which Doc Type Should I Use?

​The documentation landscape

​Decision table

​Decision flow

​Procedure granularity: UI Reference vs. Configuration Guide

​Component scope

​Common mistakes