Context and request
README.md is the unmodified Template-PSModule scaffold. It contains {{ NAME }}, {{ DESCRIPTION }}, a Greet-Entity -Name 'World' example, Import-Module -Name PSModuleTemplate, Get-Help -Examples 'CommandName', a community-file index section, and a link to a CONTRIBUTING.md that does not exist. It never mentions Format-Json, Import-Json, or Export-Json.
This is published as the module's landing page at psmodule.io/Json, so it is the first thing a prospective user sees. Every check in README validation currently fails.
Acceptance criteria.
-
These all return no matches:
Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName'
Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}'
Select-String -Path README.md -SimpleMatch -Pattern '<Command>', '<CommandName>', "-Name 'CommandName'"
Select-String -Path README.md -Pattern '^Install-Module\b'
-
Select-String -Path README.md -Pattern '^## (Commands|Capabilities)$' matches.
-
git diff --check -- README.md is clean.
-
The README answers what it is, why it matters, how to get it, how it works, and where to find more, in that order.
-
Every snippet runs as written against the published module.
Technical decisions
The implemented-module shape applies, not the placeholder shape — Json has three working commands, and the standard is explicit that a landing page with only an install snippet and a documentation link is not enough for a module that works.
Installation uses Install-PSResource. Install-Module is not acceptable in new module documentation.
The capabilities section shows one to three representative outcomes, not a command inventory. Parameter tables and exhaustive examples belong in the generated reference produced from comment-based help; duplicating them here creates drift.
The community-file index section is removed rather than fixed. The standard states a README should not act as a link farm for LICENSE, CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md, since GitHub surfaces them through its own conventions.
Nothing unique is lost in this rewrite. The rule about relocating rather than deleting prerequisites, setup guidance, operational notes, and upstream attribution does not bite here, because the file has never been customized — there is no unique content to preserve.
Get-Help examples name a real command, Get-Help -Name Format-Json -Examples, so the snippet runs as written.
^README\.md$ is in the default ImportantFilePatterns, so this change triggers the full module workflow. It is documentation-only in substance and should carry the NoRelease or Docs behaviour so it does not present as an API change.
PR #22 already covers this ground. Reconcile it against these criteria rather than opening a competing pull request.
Implementation plan
Context and request
README.mdis the unmodifiedTemplate-PSModulescaffold. It contains{{ NAME }},{{ DESCRIPTION }}, aGreet-Entity -Name 'World'example,Import-Module -Name PSModuleTemplate,Get-Help -Examples 'CommandName', a community-file index section, and a link to aCONTRIBUTING.mdthat does not exist. It never mentionsFormat-Json,Import-Json, orExport-Json.This is published as the module's landing page at psmodule.io/Json, so it is the first thing a prospective user sees. Every check in README validation currently fails.
Acceptance criteria.
These all return no matches:
Select-String -Path README.md -Pattern '^## (Commands|Capabilities)$'matches.git diff --check -- README.mdis clean.The README answers what it is, why it matters, how to get it, how it works, and where to find more, in that order.
Every snippet runs as written against the published module.
Technical decisions
The implemented-module shape applies, not the placeholder shape —
Jsonhas three working commands, and the standard is explicit that a landing page with only an install snippet and a documentation link is not enough for a module that works.Installation uses
Install-PSResource.Install-Moduleis not acceptable in new module documentation.The capabilities section shows one to three representative outcomes, not a command inventory. Parameter tables and exhaustive examples belong in the generated reference produced from comment-based help; duplicating them here creates drift.
The community-file index section is removed rather than fixed. The standard states a README should not act as a link farm for
LICENSE,CONTRIBUTING.md,SECURITY.md, andCODE_OF_CONDUCT.md, since GitHub surfaces them through its own conventions.Nothing unique is lost in this rewrite. The rule about relocating rather than deleting prerequisites, setup guidance, operational notes, and upstream attribution does not bite here, because the file has never been customized — there is no unique content to preserve.
Get-Helpexamples name a real command,Get-Help -Name Format-Json -Examples, so the snippet runs as written.^README\.md$is in the defaultImportantFilePatterns, so this change triggers the full module workflow. It is documentation-only in substance and should carry theNoReleaseorDocsbehaviour so it does not present as an API change.PR #22 already covers this ground. Reconcile it against these criteria rather than opening a competing pull request.
Implementation plan
Install-PSResourceinstallation sectionFormat-Json,Import-Json, andExport-Jsonpsmodule.io/Jsonwith realGet-CommandandGet-Helpsnippets