📖 [Docs]: Style guides cover image accessibility, PowerShell matching, and requirement IDs#16
Merged
Marius Storhaug (MariusStorhaug) merged 25 commits intoJul 6, 2026
Conversation
Marius Storhaug (MariusStorhaug)
added
the
documentation
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 13:22
View session
There was a problem hiding this comment.
Pull request overview
Updates the documentation standards to cover previously unspecified authoring guidance across Markdown, PowerShell, and spec-driven requirements, so contributors have a single consistent source of truth.
Changes:
- Adds Markdown guidance on reference-style links, using backticks for identifiers, and requiring descriptive image alt text.
- Adds PowerShell guidance on choosing matching operators and declaring immutable values via
Set-Variableoptions. - Defines the requirement identifier convention in Spec-Driven Development (
F1/N1style).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/docs/Coding-Standards/Markdown.md | Adds link, inline-code, and image accessibility conventions to the Markdown standard. |
| src/docs/Coding-Standards/PowerShell/index.md | Adds guidance for text matching operators and declaring read-only/constant variables. |
| src/docs/Ways-of-Working/Spec-Driven-Development.md | Clarifies the requirement identifier labeling convention for functional/non-functional requirements. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 13:26
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 13:30
View session
Marius Storhaug (MariusStorhaug)
added a commit
to PSModule/Process-PSModule
that referenced
this pull request
Jul 5, 2026
…te (#349) The Markdown and PowerShell style instruction files have been removed from this repository. Their content now lives in the PSModule documentation site under the new **Style Guides** section, giving contributors and agents a single, browsable source of truth for coding conventions. ## Changed: Instruction files moved to the docs site The `.github/instructions/md.instructions.md` and `.github/instructions/pwsh.instructions.md` files (and the now-empty `instructions` folder) have been removed. The same guidance is published — and expanded with a new GitHub Actions guide — at the docs site: - Companion PR: PSModule/docs#43 adds the Style Guides section. This is an internal maintenance change. It does not affect the shipped artifact or any workflow behavior. ## Technical Details - Deleted `.github/instructions/md.instructions.md` and `.github/instructions/pwsh.instructions.md`. - Content migrated verbatim to `src/docs/Style-Guides/Markdown.md` and `src/docs/Style-Guides/PowerShell.md` in `PSModule/docs`. ## Downstream coverage The MSX documentation site consumes this guidance and adds the few authoring conventions that were not carried over verbatim — image alt text, PowerShell matching operators (`-like`/`-match`/`-c`) and read-only constants, and requirement-identifier formatting — in [MSXOrg/docs#16](MSXOrg/docs#16).
…and append-only IDs in the spec guide
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 15:38
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 16:48
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 5, 2026 16:54
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:45
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:50
View session
#18 landed the reuse-hierarchy and "PowerShell is .NET" standard on main. Drop this branch's parallel "Prefer .NET for the actual work" section in favour of that version, and keep the two idioms unique to this branch (matching operators and read-only/constant values).
… comment-based help on every function
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 09:30
View session
…xtension case-insensitively
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 09:37
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 09:43
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 09:46
View session
…n scripts Documentation exists so a reader or agent can understand what a unit does and how to use it without reading its body, which is as true for an internal helper as for a public command. Broaden the Functions comment-based-help rule from public functions to every function, state in Scripts that a script starts with the same help structure as a function, and reconcile the Documentation standard so its public-surface minimum reads as a floor, not a ceiling.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 11:02
View session
Marius Storhaug (MariusStorhaug)
deleted the
docs/15-style-guide-authoring-gaps
branch
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.
The coding and spec standards now answer four authoring questions they were silent on: how to make images accessible, which PowerShell operator to reach for when matching text, when to prefer .NET over cmdlets, and how requirement identifiers are written. This closes the gaps left when the PSModule instruction files were retired into a docs site, so contributors and agents keep one complete source of truth.
New: Image accessibility and link conventions in the Markdown standard
The Markdown standard now states that every image carries descriptive alt text — so it serves screen readers and still says something when the image fails to load — and that a repeated or long link may be written reference-style. It also spells out that code, commands, filenames, and identifiers belong in backticks rather than emphasis.
New: PowerShell standard — matching, constants, and preferring .NET
The PowerShell standard now covers text matching —
-likefor wildcards,-matchfor regular expressions, and the-cprefix for case-sensitive comparison — how to declare a value that must not change withSet-Variable -Option ReadOnly, and a Prefer .NET for the actual work principle: reach for the .NET base class library on hot paths and where behaviour must be exact, and keep cmdlets for readable glue. This mirrors the ai-platform PowerShell standard.New: Requirement identifiers and normative language in Spec-Driven Development
Spec-Driven Development now defines how requirements are identified and written: functional requirements are
FR1,FR2,FR3and non-functional onesNFR1,NFR2,NFR3, each given its own heading with a stable, explicit anchor (### FR1 — <statement> { #fr1 }) so it can be referenced as[FR1](#fr1)and reworded without breaking the link. Identifiers are append-only — never renumbered or reused, and a removed requirement simply disappears (git holds the history). Requirements are written with the BCP 14 keywords (MUST / SHOULD / MAY, and the rest of the set) so obligations are unambiguous.Technical Details
Additions land in existing pages, so the standards stay navigable and the generated index is unchanged:
src/docs/Coding-Standards/Markdown.md— the "Style beyond the linter" section.src/docs/Coding-Standards/PowerShell/index.md— the "Idioms and pitfalls" section plus a new "Prefer .NET for the actual work" section.src/docs/Ways-of-Working/Spec-Driven-Development.md— the "Requirements" section..github/scripts/Test-DocumentationLink.ps1— the link checker now recognises explicit{ #id }anchors and validates reference-style link definitions, and it uses native .NET ([System.IO.File]::Exists,[System.IO.Path]::Combine) on its per-link hot path, following the new principle.Requirement identifiers use the
FR/NFRscheme with text-independent attr_list anchors ({ #fr1 }), which Zensical renders natively, and normative language anchored to BCP 14 (RFC 2119 + RFC 8174). This supersedes the earlierF1/N1idea — the PSModuleFR-001/NFR-001non-breaking-hyphen rule does not apply, since these anchors are text-independent. No lint configuration changes — the deliberate markdownlint relaxations (line length, list-marker style, blank-line rules) stand. Verified locally: markdownlint, PSScriptAnalyzer,Update-DocumentationIndex.ps1 -Check, andTest-DocumentationLink.ps1all pass.Related issues