Documentation Standards

Documentation Standards

Instructions for creating and maintaining user-facing documentation in the docs/ folder.

Structure Requirements

File Header

Every doc file must start with:

# {Title}

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

Adjust path depth for nested folders (for example: ../../VERSION.md, ../../../VERSION.md).

Single H1 Rule

Each file has exactly ONE H1 heading (the title). Use H2+ for all other sections.

Link Style

• Use relative links for internal docs (example pattern: Quickstart -> quickstart.md)
• For root file references, increase ../ depth based on folder nesting (for example: ../VERSION.md, ../../VERSION.md)
• Use reference-style links for external URLs
• No broken links (validated in CI)

Current Architecture (as of 2026-02-03)

Agents (8 total)

Skills (8 total)

Prohibited References

Do NOT reference these removed agents/skills:

• ❌ diagram.agent.md → Use azure-diagrams skill
• ❌ adr.agent.md → Use azure-adr skill
• ❌ docs.agent.md → Use azure-artifacts skill
• ❌ azure-workload-docs skill → Use azure-artifacts skill
• ❌ azure-deployment-preflight skill → Merged into deploy agent
• ❌ orchestration-helper skill → Deleted (absorbed into conductor)
• ❌ github-issues / github-pull-requests skills → Use github-operations
• ❌ gh-cli skill → Merged into github-operations
• ❌ _shared/ directory → Use azure-defaults + azure-artifacts skills

Content Principles

Validation

Documentation is validated in CI (warn-only):

• No references to removed agents
• Version numbers match VERSION.md
• No broken internal links
• Markdown lint passes