Vox Documentation Style Guide

Vox Documentation Style Guide

This guide establishes the standards for writing and organizing Vox documentation. Our goal is to provide high-fidelity, engineering-first technical guidance for both human developers and AI agents.

1. The Diátaxis Framework

All documentation must fall into one of these four categories:

Category	Goal	Tone	Placement
Tutorial	Learning a new skill	Pedagogical, step-by-step	tut-*.md
How-To Guide	Solving a specific problem	Practical, goal-oriented	how-to-*.md
Explanation	Understanding a concept	Theoretical, context-rich	expl-*.md
Reference	Technical information	Factual, concise, neutral	ref-*.md or api/

2. Technical Standards

Code Snippets

• Testable: All snippets in tutorials and how-to guides should be complete enough to compile.
• Annotated: Use comments to explain non-obvious logic, especially Vox-specific decorators.
• Language Tags: Always use vox, rust, bash, or json tags for syntax highlighting.

Voice and Tone

• Engineering-First: Focus on technical unification, type safety, and performance.
• Active Voice: “The compiler generates…” instead of “Code is generated by the compiler.”
• No Fluff: Avoid “magic,” “premium,” or “easy.” Use “integrated,” “high-performance,” or “ergonomic.”

3. Structural Rules

• Header Levels: Use H1 only for the page title. Use H2 and H3 for internal sections.
• Cross-linking: Always link to the Reference when mentioning a decorator or CLI flag for the first time in a guide.
• Alerts:
  • > [!NOTE]: For technical context or “good to know” info.
  • > [!IMPORTANT]: For critical architectural requirements.
  • > [!TIP]: For performance optimizations or ergonomic shortcuts.

4. AI & Agent Friendliness

• Clear Metadata: Use frontmatter or clear H1 tags to help AI agents index the page.
• Descriptive Links: Use Technical Reference instead of here.
• Structured Data: Use tables for configuration flags or API parameters.