"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:

CategoryGoalTonePlacement
TutorialLearning a new skillPedagogical, step-by-steptut-*.md
How-To GuideSolving a specific problemPractical, goal-orientedhow-to-*.md
ExplanationUnderstanding a conceptTheoretical, context-richexpl-*.md
ReferenceTechnical informationFactual, concise, neutralref-*.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.