Documentation standard

Standard scope

Applies to: All HCS-governed repos — prose, Markdown, and diagram conventions Domain: documentation Status: Active

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.

This file is scoped to platform-agnostic prose rules: Markdown conventions, diagram rules, heading case, and commit-message prose. For which documentation generator (MkDocs Material, Docusaurus, etc.) a given repo uses, see docs-platforms.md.

---

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
AGENTS.md (canonical) + CLAUDE.md (Claude Code shim, imports AGENTS.md)	AI coding agents/clients	Repo context loaded automatically at session start. See the agents standard.

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

README.md must include

1. What this project is — one paragraph, plain language, no jargon
2. Prerequisites — what you need installed or configured before using it
3. Quick start — minimum steps to get it running or useful
4. Links to full documentation — if a doc site exists, link to it; otherwise link to key Markdown files
5. Contributing — how to submit changes (even if it's just "open a PR")
6. 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

MkDocs Material is the HCS default documentation generator. Docusaurus is sanctioned for the TierPoint official documentation portal and AzureLocal's public community portal. VitePress is sanctioned for the Platform site and is the default for documentation sites in the private tierpoint-prodtech scope. See docs-platforms.md for the framework policy — do not reproduce its assignment matrix here.

---

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.

---

Emojis

Do not use emojis in documentation — headings, prose, tables, commit messages, or PR descriptions. Use MkDocs Material admonitions (see below) or plain text emphasis instead of an emoji to draw attention to something.

---

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.