Documentation standard¶

All documentation across HCS projects is Markdown. No Word documents, no PDFs, no Google Docs committed to repos. If it needs to be in a repo, it is Markdown.

Required files in every repo¶

File	Audience	Purpose
`README.md`	Public — anyone who opens the repo	What the project is, prerequisites, quick start, links to full docs
`CLAUDE.md`	Claude Code	Repo context loaded automatically at session start. See Claude Code standard.

Both files must exist before any functional work is committed to a repo.

README.md must include¶

What this project is — one paragraph, plain language, no jargon
Prerequisites — what you need installed or configured before using it
Quick start — minimum steps to get it running or useful
Links to full documentation — if a doc site exists, link to it; otherwise link to key Markdown files
Contributing — how to submit changes (even if it's just "open a PR")
License — state the license and link to the LICENSE file

Diagrams¶

All diagrams use draw.io. No Visio, no Lucidchart, no PowerPoint shapes exported as images.

Required: commit the .drawio XML file. The XML is the source of truth.

Required: export a .png alongside the .drawio file and commit it. This lets the diagram render in GitHub/ADO repo browsers without requiring draw.io to be installed.

Never: commit only a .png without the .drawio source.

File naming: diagram-name.drawio and diagram-name.png in the same directory.

docs/
└── architecture/
    ├── identity-model.drawio
    └── identity-model.png

Documentation sites¶

Projects that require a browsable documentation site use MkDocs with the mkdocs-material theme.

Reference implementation: azurelocal-ranger (org: azure-local-cloud). Use it as the template when setting up a new doc site.

Key requirements: - mkdocs.yml at the repo root - docs/ folder with index.md as the landing page - Dark mode toggle enabled - Search plugin enabled - Navigation tabs for top-level sections - mike for versioned documentation when the project has public releases

Do not use any other static site generator. Do not use GitHub Pages Jekyll. Do not use Docusaurus unless there is a compelling reason approved by Kris.

Commit message format¶

type(scope): short description under 72 characters

The description is in the imperative mood — "add", "fix", "update", not "added", "fixed", "updated".

Type	Use for
`feat`	New feature or capability
`fix`	Bug fix
`docs`	Documentation only — no code changes
`chore`	Maintenance: dependency updates, config, tooling
`refactor`	Code restructure with no feature change or bug fix
`test`	Adding or updating tests

Examples: - feat(identity): add managed identity registry - fix(scripts): handle empty KV secret gracefully - docs(standards): update scripting naming conventions - chore(deps): update mkdocs-material to 9.6

ADO work item link goes in the commit body or PR description: AB#1234

Heading style¶

Use sentence case in all headings. Never title-case every word.

# This is the correct heading style
## This subsection is also correct

# This Is Wrong
## Never Do This In Headings

The page title (H1) is the only heading where the first letter of the first word is capitalized. All other words are lowercase unless they are proper nouns.

Code blocks¶

Always specify the language for every code block. This enables syntax highlighting in every renderer.

    ```powershell
    Set-StrictMode -Version Latest
    ```

    ```yaml
    trigger:
      branches:
        include:
          - main
    ```

    ```bash
    az login
    ```

Never use a bare triple-backtick block without a language identifier.

Abbreviations¶

Write it out. Do not use abbreviations in document titles, section headings, or the first occurrence in a document.

"SPN" is acceptable after the first occurrence where you write "service principal (SPN)"
"PAT" is acceptable after "personal access token (PAT)"
"KV" is not acceptable — always write "Key Vault"
"ADO" is acceptable after "Azure DevOps (ADO)"

No Word docs¶

If someone sends a Word document and asks for it to be committed to a repo, convert it to Markdown first. If conversion is not practical, store a link to it in SharePoint or OneDrive and document that link in a Markdown file in the repo. Word documents are not committed to any repo under any circumstance.

draw.io tooling¶

Install the VS Code extension hediet.vscode-drawio (Draw.io Integration). This extension lets you edit .drawio files directly in VS Code with full diagram UI, no browser required.

Extension ID: hediet.vscode-drawio
Install:      ext install hediet.vscode-drawio

Diagram naming conventions:

Convention	Rule
Source file	`<name>.drawio` — committed, always present
Export	`<name>.drawio.svg` or `<name>.png` — committed alongside source
Location	Same directory as the document that references the diagram
Naming	`kebab-case` — `identity-model.drawio`, `network-topology.drawio`

Never commit only the export without the .drawio source. The XML is the source of truth.

MkDocs Material admonitions¶

MkDocs Material supports these admonition types. Use them to draw attention to important content:

Syntax	Renders as	Use for
`!!! note`	Blue info box	Additional context, non-critical clarification
`!!! tip`	Green tip box	Best practice, optimization hint
`!!! info`	Blue info box	Background information
`!!! warning`	Orange warning box	Gotchas, footguns, things that will break if ignored
`!!! danger`	Red danger box	Destructive or irreversible actions
`!!! success`	Green success box	Confirmation of correct state
`!!! example`	Purple example box	Code examples, walkthroughs

!!! warning "Domain join is irreversible"
    Once a node is joined to the domain, the local Administrator account is
    disabled. Ensure Key Vault credentials are loaded before proceeding.

Foldable versions use ??? instead of !!!:

??? tip "Optional reading — credential resolution order"
    Scripts resolve credentials in this order: ...

Badge conventions¶

Badges in README.md files use shields.io format. Use them to communicate repo status at a glance.

Standard badges for HCS repos:

![ADO Pipeline](https://img.shields.io/azure-devops/build/hybridcloudsolutions/<project-id>/<pipeline-id>?label=build)
![License](https://img.shields.io/badge/license-MIT-blue)
![PowerShell](https://img.shields.io/badge/PowerShell-7%2B-blue?logo=powershell)

Only add badges that are maintained. A broken or always-failing badge is worse than no badge. Do not add badges for services that are not configured for the repo.