# Documentation Style Guide

## Voice & Tone
- Second person ("you"), present tense, active voice
- Direct and concise - no filler phrases like "In this guide, we will..."
- Professional but approachable

## Headings
- H1 (`#`) = page title only, used ONCE per page
- H2 (`##`) = major sections
- H3 (`###`) = subsections
- Never skip levels (no H1 -> H3)

## Code Blocks
- Always specify language: ```python, ```bash, ```yaml, ```typescript
- Use `title="filename"` for file references: ```python title="orchestrator/cli.py"
- Keep examples minimal and runnable

## Links
- Use relative paths: `../tutorials/getting-started.md`
- Link text should describe the destination, not "click here"

## Admonitions (MkDocs Material)
- `!!! tip` - Best practices and recommendations
- `!!! warning` - Gotchas and common mistakes
- `!!! note` - Additional context or background
- `!!! example` - Concrete examples
- `!!! danger` - Security warnings or data loss risks

## Terminology (use consistently)
- "spec" (not "specification" or "test spec")
- "pipeline" (not "workflow" when referring to execution modes)
- "dashboard" (not "UI", "web app", or "frontend")
- "Quorvex AI" (product name, always capitalized)
- "Playwright" (always capitalized)

## Format by Diataxis Category

### Tutorials (docs/tutorials/)
- Start with a goal statement: "In this tutorial, you will..."
- List prerequisites clearly
- Numbered steps with expected output after each
- End with "What You Learned" summary + "Next Steps" links
- Include complete, copy-pasteable commands
- Never assume prior knowledge of the system

### How-to Guides (docs/guides/)
- Start with a problem statement: "How to..."
- List prerequisites
- Numbered steps focused on the task
- Include a verification step at the end
- Link to related guides
- Assume basic familiarity with the system

### Reference (docs/reference/)
- No opinions or recommendations
- Exhaustive tables with consistent columns
- Every flag, option, and parameter documented
- Zero prose - just facts
- Alphabetical or logical ordering

### Explanation (docs/explanation/)
- Explains "why" not "how"
- Include Mermaid diagrams where helpful
- Discuss trade-offs and design decisions
- Link to relevant how-to guides for practical steps
- Can be longer and more discursive

## Page Structure Template

```markdown
# Page Title

Brief one-sentence description of what this page covers.

## Section 1

Content...

## Section 2

Content...

## Related

- Related page: `../category/page.md`
```
