Repository navigation
MSX documentation leads with its subject - #295
Open
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Open
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Conversation
There was a problem hiding this comment.
🟢 Approved
The review reports no active issues with the documentation wording cleanup.
No open issues 🎉
What changed in this PR
This prose-only update makes MSX’s shared documentation lead with its subjects, rules, and contracts rather than descriptions of the pages themselves. It spans coding standards, ways of working, and capability guidance.
Changes:
- Removes redundant introductions and document self-references.
- Rephrases scope, ownership, and enforcement statements around the subjects they govern.
- Preserves navigation metadata, code samples, and product contracts; no adoption action is required.
| File | Description |
|---|---|
| src/docs/Ways-of-Working/Workflow.md | Makes stage-discovery instructions more direct. |
| src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md | Refocuses maintenance wording on workflow guidance. |
| src/docs/Ways-of-Working/Workflow-Stages/index.md | Describes stage procedures directly. |
| src/docs/Ways-of-Working/Repository-Type-Property.md | Leads with the classification mechanism. |
| src/docs/Ways-of-Working/Repository-Standard.md | Clarifies baseline inheritance and implementation ownership. |
| src/docs/Ways-of-Working/Principles/index.md | Refocuses wording on principles and their relationships. |
| src/docs/Ways-of-Working/Principles/Engineering-Practices.md | States evergreen guidance scope directly. |
| src/docs/Ways-of-Working/PR-Format.md | Leads with the shared title and description format. |
| src/docs/Ways-of-Working/Organization-Standard.md | Refocuses prose on organization requirements. |
| src/docs/Ways-of-Working/Issues/Types/index.md | Makes the issue-type introduction declarative. |
| src/docs/Ways-of-Working/Issues/Process/Lifecycle.md | Describes issue evolution through workflow phases. |
| src/docs/Ways-of-Working/Issues/Process/index.md | Makes the issue-process introduction declarative. |
| src/docs/Ways-of-Working/Issues/index.md | Removes a redundant introductory sentence. |
| src/docs/Ways-of-Working/index.md | Leads with shared practices and their uses. |
| src/docs/Ways-of-Working/DevOps-Reference.md | Removes introductory boilerplate and its separator. |
| src/docs/Ways-of-Working/Continuous-Practices.md | Removes a redundant page description. |
| src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md | Removes a self-description of the page’s scope. |
| src/docs/Ways-of-Working/Comparative-Review-Orchestration.md | Describes the review process and scope directly. |
| src/docs/Ways-of-Working/Branching-and-Merging.md | Distinguishes written requirements from ruleset enforcement. |
| src/docs/Vision/index.md | Removes self-description while retaining mission context. |
| src/docs/Initiatives/index.md | Refocuses prose on target contracts and canonical documentation. |
| src/docs/index.md | Names MSXOrg/docs as the canonical source. |
| src/docs/Dictionary/index.md | Leads with shared terminology use. |
| src/docs/Coding-Standards/YAML.md | States baseline precedence directly. |
| src/docs/Coding-Standards/TypeScript.md | States the relationship to baseline rules directly. |
| src/docs/Coding-Standards/Testing.md | Refocuses wording on the shared testing policy. |
| src/docs/Coding-Standards/Terraform.md | States the relationship to baseline rules directly. |
| src/docs/Coding-Standards/PowerShell/Version-Constraints.md | Refocuses dependency-policy and syntax relationships. |
| src/docs/Coding-Standards/PowerShell/Requires-Modules.md | Removes redundant version-specification self-description. |
| src/docs/Coding-Standards/PowerShell/Messaging.md | Describes messaging purposes and logging boundaries directly. |
| src/docs/Coding-Standards/PowerShell/index.md | Refocuses baseline, formatting, and toolchain authority wording. |
| src/docs/Coding-Standards/Natural-Language.md | Leads directly with the project dialect. |
| src/docs/Coding-Standards/Naming.md | Attributes scope limits to the filename convention. |
| src/docs/Coding-Standards/Markdown.md | Refocuses linting, configuration authority, and link-check wording. |
| src/docs/Coding-Standards/GitHub-Actions.md | Removes self-references from workflow-authoring guidance. |
| src/docs/Capabilities/vscode-extension-framework/spec.md | States framework ownership and documentation boundaries directly. |
| src/docs/Capabilities/vscode-extension-framework/design.md | Leads with framework components and their requirements. |
| src/docs/Capabilities/repository-governance/design.md | Refocuses reconciliation and enforcement prose. |
| src/docs/Capabilities/release-management/design.md | Leads with release mechanics and the lifecycle contract. |
| src/docs/Capabilities/release-management/design-publishing-targets.md | Describes destination-specific contracts directly. |
| src/docs/Capabilities/release-management/accept-moved-release-tags.md | Leads with the moving-tag refresh condition. |
| src/docs/Capabilities/powershell-on-github/design.md | Leads with reusable implementation components. |
| src/docs/Capabilities/merge-automation/design.md | Makes the specification link description subject-focused. |
| src/docs/Capabilities/downstream-release-propagation/design.md | Makes the specification link description subject-focused. |
| src/docs/Capabilities/deployment/spec.md | Describes the requirements–implementation boundary directly. |
| src/docs/Capabilities/deployment/designs/index.md | Refocuses wording on provider-specific designs. |
| src/docs/Capabilities/deployment/designs/azure-from-github.md | Leads with the deployment workflow and technology combination. |
| src/docs/Capabilities/dependency-updates/design.md | Makes the specification link description subject-focused. |
| src/docs/Capabilities/agentic-development/spec.md | Refocuses conformance and framework link descriptions. |
| src/docs/Capabilities/agentic-development/plugin-distribution.md | Removes self-description from named-intent guidance. |
| src/docs/Capabilities/agentic-development/design.md | Makes requirements and framework link descriptions direct. |
| src/docs/Capabilities/agentic-development/conformance.md | Leads with conformance checks and baseline obligations. |
| src/docs/Capabilities/agentic-development/AGENTS.template.md | Clarifies that only the fenced block forms the router. |
Review effort: Balanced
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 12, 2026 18:26
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
MSX guidance starts with the rules, procedures, behavior, and designs readers need instead of unnecessary document self-description. Useful scope, authority, rationale, and evidence stay intact. No adoption action is required; product and process contracts do not change.
Changed: Guidance leads with its subject
The sweep inventories the 126 remaining authored pages and makes focused prose edits to 53 of them: coding standards, ways of working, capability guidance, and section introductions. Redundant introductions are removed. Useful source and scope statements describe the subject directly rather than describe the page.
Navigation front matter, headings, links, code samples, diagrams, tables, and generated index regions remain unchanged. Operational ownership, product versions, observation dates, decision status, requirements, mechanisms, alternatives, and rationale remain subject facts. Runtime router and template contents are unchanged.
Technical details
Source and scope. The accepted baseline is
e0178c9dc2cce3c09c7792ddff5b14f761a7d9e7, which merged #293. The reviewed candidate is51db56a3425f3b9a43cbc77b49f18720b09fdf8b. Its three focused commits change only authored Markdown prose: 53 files, 102 insertions, and 120 deletions. The four pages covered by the earlier change are unchanged. The reusable rule remains at its canonical source: Subject-focused content.Preservation. A base-to-candidate audit confirms identical front matter, headings and heading attributes, fenced code and diagrams, Markdown tables, generated index regions, inline code, link destinations, and HTML anchors across all 53 changed pages. The inventory remains 130 pages, with four exclusions and no added, removed, or renamed pages. Context review preserves the meaning of rewritten scope and authority statements.
CI evidence: Docs and Cross-repository links.
The delivery issue's inventory, baseline checks, three content slices, preservation audit, local validation, final diff review, and convergence pass are complete. No product implementation or integration-template change is required because the supported contracts and executable examples are unchanged. The Pages route does not invoke versioned Release Management.
Issue convergence. Searched open issues for subject-focused wording, self-description, and boilerplate, and checked overlapping documentation work. #67, #274, #276, #283, and #286 remain outside this prose cleanup and are not resolved by it. No additional issue fully converges. Only the scoped delivery Task is linked for closure.
Related references