Skip to content

Move standards/*.mdx into docs/standards/ to consolidate under docs/ #6

@kristopherjturner

Description

@kristopherjturner

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

  1. 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).
  2. 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`.
  3. `templates/_common/STANDARDS.md` — same URL, update the stub template.
  4. ADR-0002 — references `platform/standards/` as the canonical path; update.
  5. `standards/README.md` — becomes the `docs/standards/index.md` (merge or replace).
  6. 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

  • Agreed: move to `docs/standards/content/` (content separate from how-to pages)
  • Agreed: merge flat into `docs/standards/` (simpler, content and how-to coexist)
  • Rejected: keep `/standards/` at root — the external-link stability and sync simplicity outweigh the structural inconsistency

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions