| 1 | --- |
| 2 | name: "docs-standards" |
| 3 | description: "Microsoft Style Guide + Squad-specific documentation patterns" |
| 4 | domain: "documentation" |
| 5 | confidence: "high" |
| 6 | source: "earned (PAO charter, multiple doc PR reviews)" |
| 7 | --- |
| 8 | |
| 9 | ## Context |
| 10 | |
| 11 | Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. |
| 12 | |
| 13 | ## Patterns |
| 14 | |
| 15 | ### Microsoft Style Guide Rules |
| 16 | - **Sentence-case headings:** "Getting started" not "Getting Started" |
| 17 | - **Active voice:** "Run the command" not "The command should be run" |
| 18 | - **Second person:** "You can configure..." not "Users can configure..." |
| 19 | - **Present tense:** "The system routes..." not "The system will route..." |
| 20 | - **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements) |
| 21 | |
| 22 | ### Squad Formatting Patterns |
| 23 | - **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data |
| 24 | - **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy |
| 25 | - **Experimental warnings:** Features in preview get callout at top |
| 26 | - **Cross-references at bottom:** Related pages linked after main content |
| 27 | |
| 28 | ### Structure |
| 29 | - **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)** |
| 30 | |
| 31 | ### Test Sync Rule |
| 32 | - **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 |
| 33 | |
| 34 | ## Examples |
| 35 | |
| 36 | ✓ **Correct:** |
| 37 | ```markdown |
| 38 | # Getting started with Squad |
| 39 | |
| 40 | > ⚠️ **Experimental:** This feature is in preview. |
| 41 | |
| 42 | Try this: |
| 43 | \`\`\`bash |
| 44 | squad init |
| 45 | \`\`\` |
| 46 | |
| 47 | Squad helps you build AI teams... |
| 48 | |
| 49 | --- |
| 50 | |
| 51 | ## Install Squad |
| 52 | |
| 53 | Run the following command... |
| 54 | ``` |
| 55 | |
| 56 | ✗ **Incorrect:** |
| 57 | ```markdown |
| 58 | # Getting Started With Squad // Title case |
| 59 | |
| 60 | Squad is a tool which will help users... // Third person, future tense |
| 61 | |
| 62 | You can install Squad with npm & configure it... // Ampersand in prose |
| 63 | ``` |
| 64 | |
| 65 | ## Anti-Patterns |
| 66 | |
| 67 | - Title-casing headings because "it looks nicer" |
| 68 | - Writing in passive voice or third person |
| 69 | - Long paragraphs of dense text (breaks scannability) |
| 70 | - Adding doc pages without updating test assertions |
| 71 | - Using ampersands outside code blocks |