📖 [Docs]: Bootstrap the MSX vision and ways-of-working site by MariusStorhaug · Pull Request #1 · MSXOrg/docs

Marius Storhaug (MariusStorhaug) · 2026-06-29T10:51:53Z

MSX Docs is the top-of-tree documentation for the MSX ecosystem — the single home for the vision, principles, ways of working, and coding standards that every organization, repository, and agent inherits. It is written once and referenced everywhere. The site is built with Zensical and published to GitHub Pages at msxorg.github.io/docs.

The vision site

The documentation is organised into four areas:

Vision — the mission and the philosophy of easy, fast, and safe, and how the why cascades into everything below it.
Ways of Working — how work flows from idea to delivery: workflow, principles, engineering taste, goal-setting, definition of ready and done, issue and pull-request conventions, commit conventions, branching and merging, review etiquette, repository segmentation, README-driven context, git worktrees, and continuous practices.
Coding Standards — language-agnostic standards for naming, code layout, functions, error handling, documentation, testing, performance, and security.
Ecosystem — where the vision comes to life across organizations and repositories.

Each section carries an auto-generated index — a table of its pages with one-line descriptions, built from page front matter — so a reader or an agent can start at the top and drill down, section to page, to the document that fits the task.

MSX is the top org that holds the vision; the organizations and repositories it points to are where that vision is demonstrated. The vision is stable, and the products that express it can change.

Build and publishing

A Docs workflow lints the content, builds the site with Zensical, and publishes to GitHub Pages on every push to main. Pull requests run lint and build; publishing happens on merge.

Source layout

src/zensical.toml — site configuration and navigation
src/docs/** — the documentation content
src/includes/**, src/overrides/** — shared snippets and theme assets
.github/workflows/Docs.yml — lint, build, and publish
.github/scripts/** — documentation tooling (index generation)
.github/linters/** — linter configuration

…ishing

… development, documentation model Per-language Coding Standards (GitHub Actions, Markdown, PowerShell, Terraform); Capabilities specs+designs (release-management, dependency-updates, downstream-release-propagation); Ways of Working: Agentic Development and Documentation Model; switch the docs index generator from Python to PowerShell (generate-indexes.ps1, run with -Check in CI).

…showcase) New MSXOrg-only "Initiatives" section placed early in the nav (right after Vision), presented like a company Products page. Absorbs and replaces Ecosystem: PSModule, AzActions, TFActions and VS Code Extensions each get a page. Repoint the front page and Vision links and cascade to Initiatives; regenerate index tables.

super-linter (textlint) requires "end-to-end" (PSModule initiative page) and "colocated" (Documentation Model description, which feeds the generated Ways of Working index).

ES modules, strict-mode typing, pinned dependencies, and the Prettier/ESLint/Vitest toolchain; builds on the language-agnostic baseline. Linked from the VS Code Extensions initiative. TypeScript is the only new language added (Shell/Python/Go/Dockerfile out of scope).

Convert the single PowerShell page into a nested standard: index.md holds the shared conventions and toolchain, with Functions, Classes, and Scripts pages each carrying doc requirements, formatting, and section structure. Repoint the nav and the GitHub Actions cross-link.

Split the single Principles page into a Principles/ folder: index.md (overview + generated table + "why these matter") and one page per theme (Purpose and Direction, AI-First Development, Software Design, Engineering Practices, Planning and Delivery) plus References. Heading levels shifted so every anchor slug is preserved; repointed all inbound links across Vision, Coding Standards, Capabilities specs, and Ways of Working; nested the nav.

A new top-level Dictionary section defining the ecosystem-specific vocabulary (Initiative, Capability, Spec, Design, Directive, Coding Standard, Principle/Practice/Philosophy, Ways of Working, Vision, Shift Left, Least privilege) plus essential shared terms, generalized from the PSModule dictionary and referencing Zensical. Each ecosystem term links to the page that covers it in full.

Copilot

Pull request overview

Bootstraps the MSX “top-of-tree” documentation site (vision, ways-of-working, coding standards, and capability specs/designs) using Zensical, with supporting automation for index generation and GitHub Pages publishing.

Changes:

Adds Zensical site configuration + full navigation tree and theme/JS overrides.
Introduces the initial docs corpus across Vision, Initiatives, Ways of Working, Coding Standards, Capabilities, and Dictionary.
Adds CI automation: lint/build/publish workflow, index-generation tooling, and repo lint/dependency config.

Reviewed changes

Copilot reviewed 73 out of 74 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`src/zensical.toml`	Zensical site config + nav
`src/overrides/assets/javascripts/tablesort.js`	Table sorting enhancement
`src/includes/links.md`	Shared link definitions stub
`src/includes/abbreviations.md`	Shared abbreviations glossary
`src/docs/index.md`	Site home page + index
`src/docs/Vision/index.md`	Vision landing page
`src/docs/Initiatives/index.md`	Initiatives index page
`src/docs/Initiatives/PSModule.md`	Initiative page: PSModule
`src/docs/Initiatives/AzActions.md`	Initiative page: AzActions
`src/docs/Initiatives/TFActions.md`	Initiative page: TFActions
`src/docs/Initiatives/VS-Code-Extensions.md`	Initiative page: VS Code extensions
`src/docs/Ways-of-Working/index.md`	Ways of Working index
`src/docs/Ways-of-Working/Workflow.md`	Workflow specification page
`src/docs/Ways-of-Working/Contribution-Workflow.md`	PR flow + Copilot loop
`src/docs/Ways-of-Working/Documentation-Model.md`	Spec/design documentation model
`src/docs/Ways-of-Working/Agentic-Development.md`	Agent consumption model
`src/docs/Ways-of-Working/Principles/index.md`	Principles index page
`src/docs/Ways-of-Working/Principles/Purpose-and-Direction.md`	Principles: purpose/direction
`src/docs/Ways-of-Working/Principles/AI-First-Development.md`	Principles: AI-first
`src/docs/Ways-of-Working/Principles/Software-Design.md`	Principles: software design
`src/docs/Ways-of-Working/Principles/Engineering-Practices.md`	Principles: engineering practices
`src/docs/Ways-of-Working/Principles/Planning-and-Delivery.md`	Principles: planning/delivery
`src/docs/Ways-of-Working/Principles/References.md`	Principles references list
`src/docs/Ways-of-Working/Engineering-Taste.md`	Judgment defaults (“taste”)
`src/docs/Ways-of-Working/Goal-Setting.md`	OKR/initiative framework
`src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md`	DoR/DoD checklists
`src/docs/Ways-of-Working/Issue-Format.md`	Standard issue template spec
`src/docs/Ways-of-Working/Issue-Hierarchy.md`	Epic/PBI/Task hierarchy
`src/docs/Ways-of-Working/PR-Format.md`	PR title/description conventions
`src/docs/Ways-of-Working/Commit-Conventions.md`	Commit message conventions
`src/docs/Ways-of-Working/Branching-and-Merging.md`	Branch/merge model
`src/docs/Ways-of-Working/Review-Etiquette.md`	Review etiquette guidance
`src/docs/Ways-of-Working/Repository-Segmentation.md`	Repo boundary guidance
`src/docs/Ways-of-Working/Readme-Driven-Context.md`	README as repo “front door”
`src/docs/Ways-of-Working/Git-Worktrees.md`	Worktree-based repo layout
`src/docs/Ways-of-Working/Continuous-Practices.md`	Continuous X / Continuous AI
`src/docs/Ways-of-Working/DevOps-Reference.md`	DevOps reading list + synthesis
`src/docs/Coding-Standards/index.md`	Coding standards index
`src/docs/Coding-Standards/Naming.md`	Naming baseline standard
`src/docs/Coding-Standards/Code-Layout.md`	Code layout baseline standard
`src/docs/Coding-Standards/Functions.md`	Functions baseline standard
`src/docs/Coding-Standards/Error-Handling.md`	Error handling baseline standard
`src/docs/Coding-Standards/Documentation.md`	Documentation baseline standard
`src/docs/Coding-Standards/Testing.md`	Testing baseline standard
`src/docs/Coding-Standards/Performance.md`	Performance baseline standard
`src/docs/Coding-Standards/Security.md`	Security baseline standard
`src/docs/Coding-Standards/GitHub-Actions.md`	GitHub Actions standard
`src/docs/Coding-Standards/Markdown.md`	Markdown authoring standard
`src/docs/Coding-Standards/PowerShell/index.md`	PowerShell standards index
`src/docs/Coding-Standards/PowerShell/Functions.md`	PowerShell functions standard
`src/docs/Coding-Standards/PowerShell/Classes.md`	PowerShell classes standard
`src/docs/Coding-Standards/PowerShell/Scripts.md`	PowerShell scripts standard
`src/docs/Coding-Standards/Terraform.md`	Terraform standard
`src/docs/Coding-Standards/TypeScript.md`	TypeScript standard
`src/docs/Capabilities/index.md`	Capabilities index
`src/docs/Capabilities/release-management/index.md`	Release mgmt capability index
`src/docs/Capabilities/release-management/spec.md`	Release mgmt spec
`src/docs/Capabilities/release-management/design.md`	Release mgmt design
`src/docs/Capabilities/dependency-updates/index.md`	Dependency updates index
`src/docs/Capabilities/dependency-updates/spec.md`	Dependency updates spec
`src/docs/Capabilities/dependency-updates/design.md`	Dependency updates design
`src/docs/Capabilities/downstream-release-propagation/index.md`	Downstream propagation index
`src/docs/Capabilities/downstream-release-propagation/spec.md`	Downstream propagation spec
`src/docs/Capabilities/downstream-release-propagation/design.md`	Downstream propagation design
`src/docs/Dictionary/index.md`	Shared vocabulary dictionary
`.github/workflows/Docs.yml`	Lint/build/publish pipeline
`.github/scripts/generate-indexes.ps1`	Index generation script
`.github/scripts/Wait-CopilotReview.ps1`	Copilot review wait helper
`.github/linters/.markdown-lint.yml`	markdownlint config
`.github/linters/.codespellrc`	codespell config
`.github/linters/.textlintrc`	textlint terminology config
`.github/dependabot.yml`	Dependabot config (Actions)
`.gitignore`	Ignore build + env artifacts
`README.md`	Repo overview + conventions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…rt, strip BOMs README now points at generate-indexes.ps1 / pwsh / -Check. Docs.yml only cancels in-progress PR runs so a Pages deploy is never cancelled mid-publish. Vendor tablesort.min.js locally instead of the unpkg CDN (self-contained build). Strip UTF-8 BOMs from generate-indexes.ps1 and Wait-CopilotReview.ps1 so shebang/#Requires work cross-platform. (dependabot cooldown is valid GA syntax — kept.)

The vendored tablesort.min.js is third-party minified code and should not be linted (eslint no-redeclare / prettier). Add FILTER_REGEX_EXCLUDE for *.min.(js|css).

Copilot

Pull request overview

Copilot reviewed 73 out of 75 changed files in this pull request and generated 2 comments.

…guard README intro list now matches the real sections (Initiatives/Capabilities/Dictionary, no Ecosystem). Add #Requires -Version 7.0 to generate-indexes.ps1.

Copilot

Pull request overview

Copilot reviewed 73 out of 75 changed files in this pull request and generated 2 comments.

…ow-list)

Copilot

Pull request overview

Copilot reviewed 74 out of 77 changed files in this pull request and generated 2 comments.

… headers

Copilot

Pull request overview

Copilot reviewed 74 out of 77 changed files in this pull request and generated 1 comment.

…ardrails

Copilot

Pull request overview

Copilot reviewed 74 out of 77 changed files in this pull request and generated no new comments.

…strategy

…n negated-boolean rule

…itHub Actions linters

…style guide (#9) ## Summary Adopts seven PowerShell and Markdown conventions our standards were missing, found by comparing our Coding Standards against the community references. The pages it edits were introduced by #1, now merged to `main`; this branch has been rebased onto `main` so it applies cleanly. **Sources analyzed:** PoshCode *PowerShell Practice and Style*; the Microsoft PowerShell-Docs style guide; and dsccommunity.org (a Hugo website with a git workflow that mirrors ours and no reusable coding standards — nothing adopted from it). ## Changes - **Tools vs. controllers, and raw output** (`Coding-Standards/PowerShell/index.md`) — Closes #2 - **Output streams, and implicit output over `return`** (`Coding-Standards/PowerShell/Functions.md`) — Closes #3 - **PowerShell error-handling idioms** — `-ErrorAction Stop`, transaction-in-`try`, avoid `$?`, copy `$_` in `catch` (`Coding-Standards/PowerShell/Functions.md`) — Closes #4 - **`[PSCredential]` parameters for secrets** (`Coding-Standards/PowerShell/index.md`) — Closes #5 - **Full parameter names, no positional arguments, standard names** (`Coding-Standards/PowerShell/index.md`) — Closes #6 - **Path handling** — avoid `~` and relative paths, use `$PSScriptRoot`, the `[Environment]::CurrentDirectory` pitfall (`Coding-Standards/PowerShell/Scripts.md`) — Closes #7 - **PowerShell code samples in docs** — `powershell` fence, `Output` block, no backtick continuation (`Coding-Standards/Markdown.md`) — Closes #8 ## Validation textlint (terminology), the documentation link checker, the index-drift check, and the DNB-spillage scan all clean. Now that the base is `main`, `Docs.yml` (lint, link validation, build) runs on this PR.

…ules strengthened (#66) PowerShell coding standards now precisely cover two tightly coupled topics: how to scope `[OutputType]` when parameter sets return different types, and what makes a parameter set name acceptable. ## New: `[OutputType]` scoping per parameter set A new subsection "**`[OutputType]` and parameter sets**" is added directly after the Section structure code example. It explains when to use a single unscoped `[OutputType]` (all sets return the same type) versus per-set scoping using `ParameterSetName`, includes a runnable snippet showing both `[OutputType]` attributes alongside `[CmdletBinding(DefaultParameterSetName = ...)]`, and states the contract: types in `[OutputType]` must match `.OUTPUTS` in comment-based help. ## Changed: Parameter set naming rule The previous bullet ("Name every parameter set with an intent-revealing name … never `Default` or `__AllParameterSets`") has been replaced with a precise rule that explains *why*: parameter set names appear verbatim in `Get-Help` syntax output and are read by callers, not just developers. The rule now lists the acceptable patterns (`ByName`, `ByPath`, `ByLiteralPath`, `ByGuid`, `WithCredential`, `AsComputerName`, `AsSession`), enumerates explicitly unacceptable names (`Default`, `__AllParameterSets`, `__DefaultParameterSet`, `ParameterSetA`, `Set1`, `Mode1`), and makes `DefaultParameterSetName` mandatory when multiple sets exist. ## Technical Details - Single file changed: `src/docs/Coding-Standards/PowerShell/Functions.md` - +20 lines, −1 line; no surrounding context altered. - Both changes shipped in one commit because `[OutputType]` scoping is meaningless without well-named parameter sets to reference. <details> <summary>Related issues</summary> - #1 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…unction help standards (#65) PowerShell comment-based help standards now include precise rules for writing `.INPUTS` and `.OUTPUTS` — covering pipeline-only scope, fully-qualified .NET type names, the two-line type + description format, the `None` template, per-type keyword repetition, and how PlatyPS renders these sections. ## New: `.INPUTS` and `.OUTPUTS` formatting rules The PowerShell Functions coding-standards page gains a dedicated sub-section under *Comment-based help (required)* that specifies exactly how to write these two sections: - **`.INPUTS`** covers pipeline input only — not all parameters. Use `None` (as the type name) with `You can't pipe objects to <CommandName>.` as the description when no pipeline input is accepted. - **`.OUTPUTS`** must match `[OutputType()]`. Repeated once per return type for multi-type functions. - Both use the fully-qualified .NET type name (`System.String`, not `[string]`). - **Two-line format:** type name alone on the first line, description indented on the next line. Putting both on one line causes MD026 (trailing period in headings) violations in PlatyPS-generated docs, since PlatyPS renders the type name as a `###` heading. - The keyword is repeated once per type when multiple types are accepted or returned. ## Technical Details - Single file changed: `src/docs/Coding-Standards/PowerShell/Functions.md` - Insertion after the existing paragraph in the *Comment-based help (required)* section; no existing content modified. - Corrected from initial single-line `System.String. Description.` format after discovering the PlatyPS MD026 constraint. <details> <summary>Related issues</summary> - #1 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Marius Storhaug (MariusStorhaug) added the documentation Improvements or additions to documentation label Jun 29, 2026

Marius Storhaug (MariusStorhaug) self-assigned this Jun 29, 2026

Marius Storhaug (MariusStorhaug) force-pushed the docs/bootstrap-vision-site branch 4 times, most recently from f9de6f5 to 949e034 Compare June 29, 2026 12:39

Add MSX vision documentation site with Zensical and GitHub Pages publ…

6a9852a

…ishing

Marius Storhaug (MariusStorhaug) force-pushed the docs/bootstrap-vision-site branch from 949e034 to 6a9852a Compare June 29, 2026 12:42

Marius Storhaug (MariusStorhaug) added 9 commits July 1, 2026 14:38

Fix textlint terminology: end-to-end and colocated

c53e42a

super-linter (textlint) requires "end-to-end" (PSModule initiative page) and "colocated" (Documentation Model description, which feeds the generated Ways of Working index).

Add the contribution workflow guide and Wait-CopilotReview script

1582122

Refine wording in the single production authority requirement

de1ad1b

Marius Storhaug (MariusStorhaug) requested a review from Copilot July 1, 2026 16:51

Copilot started reviewing on behalf of Marius Storhaug (MariusStorhaug) July 1, 2026 16:51 View session