2240 Doc Standards 0d57b4d0

Documentation Standards Reference

For use by the docs-writer skill. Consolidates rules from markdown.instructions.md and docs.instructions.md.

File Header Pattern

Every doc in docs/ must start with:

# {Title}

> [Current Version](../VERSION.md) | {One-line description}

• Version number: always read from VERSION.md (single source of truth)
• Description: one sentence summarizing the document's purpose

Heading Rules

Line Length

120 characters maximum — enforced by CI and pre-commit hooks.

Breaking strategies:

1. Sentences: break after punctuation (period, comma, em-dash)
2. Lists: continue on next line with matching indentation
3. Links: break before [ or use reference-style links
4. Tables: allowed to exceed when column content requires it

Link Conventions

Mermaid Diagrams

Every Mermaid block must include the neutral theme directive:

```mermaid
%%{init: {'theme':'neutral'}}%%
graph LR
    A --> B
```

Callout Syntax

Use GitHub-flavored callouts:

> [!NOTE]
> Informational highlight.

> [!TIP]
> Helpful advice for the reader.

> [!WARNING]
> Something that could cause issues.

Code Blocks

Always specify language after opening backticks:

• Bicep: ```bicep
• PowerShell: ```powershell
• Bash: ```bash
• JSON: ```json
• YAML: ```yaml
• Markdown: ```markdown
• Plain text: ```text

Tables

Prohibited References

These agents were removed and converted to skills. Never reference them:

Also avoid references to removed paths:

• docs/guides/ — removed
• docs/reference/ — removed
• docs/getting-started.md — superseded by docs/quickstart.md

Content Principles

Validation Commands

# Markdown lint (all files)
npm run lint:md

# Link validation
npm run lint:links

# Artifact H2 structure check
npm run validate

# Skill format validation
npm run skill:validate

# Auto-fix artifact H2 headings
npm run fix:artifact-h2 <path> [--apply]

Version Number Propagation

When VERSION.md is updated, check these files for version references:

• docs/*.md — header lines with > Version X.Y.Z
• docs.instructions.md — header template example
• scenarios/README.md — may reference version
• CHANGELOG.md — new version entry needed

Emoji Conventions in Agent/Skill Tables

Personas use consistent emoji in docs/README.md:

When adding a new agent, choose a unique emoji + persona name.