Skip to content

Documentation Standards

Canonical reference: Documentation Standards (full)
Applies to: All AzureLocal repositories
Last Updated: 2026-03-17

Principles

Principle Rule
Documentation-First Document before implementing. Keep docs current with code.
Single Source of Truth One authoritative document per topic. Cross-reference, don't duplicate.
Audience-Aware Write for operators, developers, or executives — with appropriate depth.
Actionable Step-by-step procedures, examples, prerequisites, and outcomes.

File Naming

Type Convention Pattern Example
Directories lowercase-with-hyphens ^[a-z][a-z0-9-]*$ guides/, reference/
Markdown (docs/) lowercase with hyphens *.md deployment-guide.md
Root files UPPERCASE — README.md, CHANGELOG.md, CONTRIBUTING.md
PowerShell scripts PascalCase Verb-Noun.ps1 Deploy-Solution.ps1
Config files lowercase-with-hyphens — variables.example.yml

MkDocs Material Conventions

This repo uses MkDocs Material with the following conventions:

  • Admonitions: Use !!! note, !!! warning, !!! danger, !!! info, !!! tip
  • Code blocks: Always include a language identifier (e.g., ```powershell, ```yaml)
  • Code copy: Enabled via content.code.copy
  • Mermaid diagrams: Supported via pymdownx.superfences custom fence
  • Tables: Use standard Markdown tables
  • Tabs: Use === "Tab Name" via pymdownx.tabbed

Frontmatter & Metadata

Every documentation page should include:

# Page Title

> Brief one-line description of the page's purpose.

---

Fictional Company — Infinite Improbability Corp (IIC)

All examples must use IIC. See the Examples & IIC Policy page for the full reference card.

Never Use Use Instead
contoso, fabrikam, northwind Infinite Improbability Corp
example.com, test.com improbability.cloud
Real customer names IIC naming patterns