📖 [Docs]: Process-PSModule documentation is now organized by task

[Marius Storhaug (MariusStorhaug)]

The Process-PSModule documentation now leads with how to use the pipeline. Getting started, guides, reference, and specification are separate sections, so someone looking up a setting or wiring up their first module no longer has to read the specification and design first.

New: A guided path from template to first release

Getting started is now a walkthrough rather than a single page of bullets. It covers creating the repository from the template, configuring GitHub Pages and the PowerShell Gallery API key, adding the caller workflow and settings file, and then opening the first pull request and applying a version label. Bootstrapping a brand-new module with an integration branch sits alongside it.

New: Guides for the things people actually do

Seven task-oriented pages cover calling the workflow, configuring the pipeline with worked examples, structuring a module, writing module tests, skipping individual framework tests, versioning and releases, and validating a change before review. Writing module tests is new — test discovery rules, the BeforeAll.ps1 and AfterAll.ps1 phases, and how to share expensive infrastructure across the platform matrix were previously buried inside the pipeline-stages page.

Changed: Documentation is grouped by what you are trying to do

The section was a flat list of 15 sibling pages ordered specification, design, usage. It is now four ordered sections:

Section	Purpose
Get started	Create a repository, configure it, ship a first release
Guides	Task-oriented deep dives into the pipeline's functionality
Reference	Exact contracts — settings, workflow inputs, stages, matrices, test IDs
Specification	Spec, design, and principles, for maintainers of the pipeline itself

The specification and design are still published, just last, since few readers need them to use the pipeline.

Changed: Every fact has one home

The scenario matrix, the version-label mapping, the framework test IDs, the runtime settings contract, the repository setup steps, and the dependency list were each documented in two or three places. Each now lives on one page and is linked from the others, so they can no longer drift apart. The landing page also no longer prints the same page-index table twice.

Changed: Pointer-only pages are gone

The PowerShell, Solutions, and Style-Guides sections contained nothing but links to MSXOrg docs. They are removed and the pages that referenced them now link straight to the canonical MSX standards, removing a hop.

---

Technical details

• All page moves use git mv, so file history follows the content.
• Merges and splits: index.md + workflow-overview.md → one landing page; module-anatomy.md folded into guides/structuring-your-module.md; the build-test-pack-publish.md stub replaced by guides/versioning-and-releases.md; usage.md split into guides/calling-the-workflow.md + reference/workflow-inputs.md; configuration.md split into guides/configuring-the-pipeline.md + reference/settings.md; test-authoring content extracted from pipeline-stages.md into guides/writing-module-tests.md.
• New reference pages: scenario-matrix.md, framework-test-ids.md, dependencies.md, plus a specification/index.md section landing page.
• design.md documented .github/PSModule.yml with Enabled: keys while the real authorable contract uses Skip:. Rather than restate the contract, it now links to reference/settings.md, which removes the contradiction.
• design.md also carried its own copy of the runtime Settings table that had drifted from the one in pipeline-stages.md (Test.Module.Enabled vs the actual BeforeAllEnabled/MainEnabled/AfterAllEnabled). It now links to the pipeline-stages copy.
• Linter configuration consolidated: the duplicated docs/.github/linters/* set is removed in favour of the repository-level .github/linters/*, with the codespell, markdownlint, and PSScriptAnalyzer profiles updated to cover the docs corpus.
• docs/zensical.toml nav rewritten to the four-section hierarchy. navigation.indexes is already enabled, so each section index is clickable and there are no dead nav nodes.
• Validation performed: every relative markdown link across docs/content resolves; every in-tree heading anchor referenced by a link exists; every zensical.toml nav entry points at an existing file. This also clears two pre-existing broken links to ../PowerShell/Standard/index.md in Module-Types.md and Standards.md.
• No callable workflow contract changed. .github/workflows/workflow.yml and the reusable sub-workflows are untouched; only the repository-internal Docs.yml and linter configs are modified, so there is no release impact for consumers.
• Delivery leaf: this pull request has no scoped closing Task or Bug. It needs one under Consolidate PSModule documentation into Process-PSModule and retire PSModule/docs #423 before it satisfies the Definition of Ready for Review.

Relevant issues (or links)

• Consolidate PSModule documentation into Process-PSModule and retire PSModule/docs #423

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter