Define docs standard for infrastructure diagram sources, exports, and author-only comments

[christinaausley]

Create a docs-team standard for how infrastructure diagrams are authored, exported, stored, and referenced, and define clear rules for author-only instructions in docs source. Recent cleanup removed stale internal comments, but we need a repeatable process to prevent recurrence.

Problem

• Author-facing TODOs/export instructions appeared in published docs markdown/MDX.
• No consistent standard for required diagram formats (image only vs image + PDF).
• Ownership and update workflow for diagram source files are unclear.

Scope

• Define source-of-truth for diagram files.
• Define export requirements, naming, and storage conventions.
• Define where contributor instructions belong (internal docs/process docs/templates, not page source).
• Add a lightweight reviewer checklist.
• Define handling of temporary author notes during drafting.

Out of scope

• Redesigning existing diagrams.
• Migrating all historical docs in this ticket.
• Changing diagram tooling.

Policy: author-only comments in docs source

• Do not keep author-only TODOs, export instructions, or editorial notes in published docs markdown/MDX.
• Place contributor guidance in internal process docs, contributor docs, or templates.
• If temporary notes are used during drafting, they must be removed before merge.

Enforcement

• Add a PR checklist item: No author-only comments remain in published docs files.
• Optionally add lint/check rules for common patterns, for example:
  • <!-- TODO:
  • <!-- To export:
  • <!-- before merge

Acceptance criteria

• Team standard documented in contributor/process docs.
• PR reviewer checklist published and includes author-comment check.
• Contribution guidance updated to reference the standard location for internal instructions.
• Follow-up cleanup tickets created for non-compliant pages, if needed.

Notes

Reference: PR #8254 (stale internal comments removed from 8.7 self-managed setup guides).