docs-standards

## Context Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. ## Patterns ### Microsoft Style Guide Rules - **Sentence-case headings:** "Getting started" not "Getting Started" - **Active voice:** "Run the command" not "The command should be run" - **Second person:** "You can configure..." not "Users can configure..." - **Present tense:** "The system routes..." not "The system will route..." - **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements) ### Squad Formatting Patterns - **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data - **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy - **Experimental warnings:** Features in preview get callout at top - **Cross-references at bottom:** Related pages linked after main content ### Structure - **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)** ### Test Sync Rule - **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit ## Examples ✓ **Correct:** ```markdown # Getting started with Squad > ⚠️ **Experimental:** This feature is in preview. Try this: \`\`\`bash squad init \`\`\` Squad helps you build AI teams... --- ## Install Squad Run the following command... ``` ✗ **Incorrect:** ```markdown # Getting Started With Squad // Title case Squad is a tool which will help users... // Third person, future tense You can install Squad with npm & configure it... // Ampersand in prose ``` ## Anti-Patterns - Title-casing headings because "it looks nicer" - Writing in passive voice or third person - Long paragraphs of dense text (breaks scannability) - Adding doc pages without updating test assertions - Using ampersands outside code blocks