Skip to content

Replace the Json template README with the standard module landing page #41

Description

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

  • Review PR 📖 [Docs]: README pages now use the standard module landing-page format #22 against the criteria above and continue from that branch if it is close
  • Write the overview paragraph naming the module and its scope
  • Add the Install-PSResource installation section
  • Write a capabilities section with one to three real examples using Format-Json, Import-Json, and Export-Json
  • Add the documentation section linking to psmodule.io/Json with real Get-Command and Get-Help snippets
  • Remove the community-file index section
  • Run every README validation command and confirm no matches
  • Execute each snippet against the installed module to confirm it runs as written
  • Apply the label that keeps this from presenting as an API change

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions