Keep template READMEs technically correct, GitHub-renderable, and maintainable.
- Use markdown syntax that GitHub will render (avoid docs.microsoft.com-only constructs like
[!TIP]; if needed, replace with standard headings/blockquote/correct GitHub-compatible callouts).
- Ensure labels/claims match the actual artifact(s) (e.g., don’t call something “ARM” if it’s explicitly “JSON”, or be precise with “ARM and bicep template”).
- Provide prerequisite commands that match likely tooling in the environment (prefer the Az module when applicable, and give concrete commands).
- Avoid large inline code in README files. Move substantial examples (YAML/scripts/manifests) into separate files under the repo and reference them.
- Avoid unnecessary template fragmentation when the workflow is inherently sequential (e.g., creating a SIM group always followed by creating SIMs—prefer a single template/flow where possible).
Example (GitHub-safe callout + externalized snippet):
## Note
Azure Monitor alerts may incur charges.
See `docs/alert-sample.yml` for the sample manifest.
# docs/alert-sample.yml
# (sample contents here)
Example (tooling-appropriate prerequisites):
# Prefer Az module cmdlets when available
Get-AzAdUser -UserPrincipalName $name