Problem
The platform repo currently has two `standards` locations with different purposes:
| Path |
Contents |
Purpose |
| `/standards/` |
11 `.mdx` source files + README |
Canonical standards content — what the site syncs from, what product repo stubs link to |
| `/docs/standards/` |
`consuming.md`, `contributing.md`, `authoring-guide.md`, `propagation.md`, stub `index.md` |
Documentation about the standards system — how to consume, author, contribute |
These are genuinely different things, but having a root-level `/standards/` alongside `/docs/` is inconsistent for a dedicated platform repo where everything else lives under `docs/`. A contributor landing on the repo sees two top-level standards locations and has to understand the distinction.
Proposed resolution
Move the 11 `.mdx` source files from `/standards/` into `/docs/standards/`, co-locating them with the how-to pages about the system.
The two sub-concerns could be separated:
- `docs/standards/` — index + how-to pages (consuming, contributing, authoring, propagation)
- `docs/standards/content/` — the actual `.mdx` source files
Or merged flat into `docs/standards/` if the how-to pages and the content pages can coexist cleanly in the same folder.
Downstream changes required
- Sync workflow (
azurelocal.github.io/.github/workflows/sync-standards.yml) — update the `find` path from `_platform/standards` to `_platform/docs/standards/content` (or wherever the content lands).
- 6 product repo `STANDARDS.md` stubs — all link to `https://github.com/AzureLocal/platform/tree/main/standards\`; update to new path. Affected repos: `azurelocal-avd`, `azurelocal-sofs-fslogix`, `azurelocal-loadtools`, `azurelocal-vm-conversion-toolkit`, `azurelocal-copilot`, `azurelocal-nutanix-migration`.
- `templates/_common/STANDARDS.md` — same URL, update the stub template.
- ADR-0002 — references `platform/standards/` as the canonical path; update.
- `standards/README.md` — becomes the `docs/standards/index.md` (merge or replace).
- MkDocs nav in `mkdocs.yml` — currently references `standards/consuming.md` etc.; update to new path.
Timing note
This is the right time to do it. The 6 product-repo stubs were just merged in Phase 1 (2026-04-12) and no external documentation has been published pointing to the current `/standards/` path yet. Changing the path now costs one PR per affected repo; changing it after Phase 3 rollout (when all 13 repos have adopted it) costs significantly more.
Decision needed
Once decided, execution is a single platform PR + 6 small stub-update PRs. Should be done before Phase 2 starts to avoid further baking in the current path.
Problem
The platform repo currently has two `standards` locations with different purposes:
These are genuinely different things, but having a root-level `/standards/` alongside `/docs/` is inconsistent for a dedicated platform repo where everything else lives under `docs/`. A contributor landing on the repo sees two top-level standards locations and has to understand the distinction.
Proposed resolution
Move the 11 `.mdx` source files from `/standards/` into `/docs/standards/`, co-locating them with the how-to pages about the system.
The two sub-concerns could be separated:
Or merged flat into `docs/standards/` if the how-to pages and the content pages can coexist cleanly in the same folder.
Downstream changes required
azurelocal.github.io/.github/workflows/sync-standards.yml) — update the `find` path from `_platform/standards` to `_platform/docs/standards/content` (or wherever the content lands).Timing note
This is the right time to do it. The 6 product-repo stubs were just merged in Phase 1 (2026-04-12) and no external documentation has been published pointing to the current `/standards/` path yet. Changing the path now costs one PR per affected repo; changing it after Phase 3 rollout (when all 13 repos have adopted it) costs significantly more.
Decision needed
Once decided, execution is a single platform PR + 6 small stub-update PRs. Should be done before Phase 2 starts to avoid further baking in the current path.