Guides — Content Standards
Tier: Guides | Reader phase: Configuring and Operating
What This Tier Is For
The Guides tier covers the Configuring and Operating phase of the reader journey. Documents here answer: How do I set this up, and how do I keep it running? Unlike the Concepts & Architectures tier (which explains what things are and why), and the Reference tier (which documents specifics), Guides are procedural — they take a reader from a defined start state to a defined end state, step by step.How the Two Types Relate
Document Types
Cross-Cutting Standards
The following standards apply to all document types in this tier.Prerequisites are mandatory
Every guide must open with a prerequisites section before any procedural steps. Configuration and Troubleshooting Guides use a Prerequisites heading. Upgrade Guides use Before You Begin to also cover backups, health checks, and rollback options. The label differs but the requirement does not — readers who arrive without the required context waste time, and may cause production incidents if they skip steps. Never assume the reader has what they need.Imperative mood for every action step
Every step that requires the reader to do something must use imperative mood: “Click Save”, “Set the Gateway Size to…”, “Run the following command:”. Never describe an action as an observation (“The user should click Save”).UI element names are always bold
Bold every UI label, button, field name, field value, toggle, and menu item exactly as it appears in the product. Use the> separator for navigation paths: CoPilot > Cloud Fabric > Gateways.
Verification is required where possible
Every guide should tell the reader what success looks like. If there is a meaningful way to confirm the procedure worked — a UI state to check, a CLI output to verify, a Terraform plan to review — include it.Frontmatter
All documents requiretitle, description, and keywords in frontmatter.