Finding
The guide requires code explanation tables for CLI commands, but most Azure CLI snippets do not include adjacent explanation tables.
Audit estimate:
- 158 fenced code blocks contain
az commands.
- 147 of those did not have a Markdown explanation table in the following context window.
Examples:
docs/best-practices/storage-account-design-baseline.md:70-88 creates/updates storage resources without a command/flag explanation table.
docs/tutorials/lab-guides/lab-01-blob-lifecycle-management.md:68-85 uploads data and applies a lifecycle policy without explaining required files, flags, or expected output.
Why this matters
Storage commands can change access, retention, lifecycle, replication, and cost behavior. Explanation tables make the commands auditable and help readers catch missing prerequisites before execution.
Suggested fix
- Add explanation tables after Azure CLI snippets.
- Prioritize tutorials, operations, and troubleshooting docs.
- Include variables, key flags, expected output, and safety notes for destructive or policy-changing commands.
- Add a lint/checklist rule for future
az snippets.
Finding
The guide requires code explanation tables for CLI commands, but most Azure CLI snippets do not include adjacent explanation tables.
Audit estimate:
azcommands.Examples:
docs/best-practices/storage-account-design-baseline.md:70-88creates/updates storage resources without a command/flag explanation table.docs/tutorials/lab-guides/lab-01-blob-lifecycle-management.md:68-85uploads data and applies a lifecycle policy without explaining required files, flags, or expected output.Why this matters
Storage commands can change access, retention, lifecycle, replication, and cost behavior. Explanation tables make the commands auditable and help readers catch missing prerequisites before execution.
Suggested fix
azsnippets.