Repository navigation
[documentation-writing-alignment] State glossary definitions in clear evergreen prose #554
Description
Context and request
Readers need clear, consistent definitions in the PSModule glossary and abbreviation tooltips. This Task delivers one prose-only pull request for docs/content/Dictionary/*.md and docs/includes/abbreviations.md. The reference layout stays unchanged.
Evidence and expected result
The source snapshot is PSModule/Process-PSModule@64ffb1d87f86bd5d487891fdb140b78385a00531. All 32 Dictionary pages and the abbreviation include have a full manual read before edits.
The review uses MSXOrg/docs commit 1b0d4893c8fefabe604d04393068a8ff6f848082: Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and the reference template.
The official STE overview, FAQ, and Issue 9 establish the applicable writing practices. The local PDF MD5 is 9c720341c350ed77943b2c73d01c716f, which matches the official record. Manual review covers technical nouns, en-US spelling, present-tense descriptions, active voice, short complete sentences, and direct instructions. Rule references are 1.1-1.14, 3.2, 3.5-3.6, 4.1-4.2, and 6.1-6.6. Reference copies and extracted text stay local. No full STE conformance claim follows from a scan, count, or lint result.
The following acceptance examples are recorded before edits:
| Surface | Original text | Expected property and proposed result | Technical source |
|---|---|---|---|
| Glossary opening | "Welcome to the PSModule Glossary, a reference of terms, concepts, and technologies used throughout our projects and documentation." | State the reference purpose without a greeting or collective voice: "This glossary is a reference for terms, concepts, and technologies in PSModule projects and documentation." | Pinned Documentation Model and reference template |
| Quick reference | "Common terms you might encounter:" | Use a factual statement: "The quick reference lists common PSModule terms." | Pinned Natural Language |
| Contribution note | "Found a term that should be added or need to update an existing definition? Please ..." | Preserve the procedure as a direct instruction: "To add a term or correct a definition, create an issue or submit a pull request." | Pinned Natural Language; official STE FAQ |
| API | "A set of protocols, routines, and tools for building software applications. APIs specify how software components should interact and are used when programming graphical user interface (GUI) components." | Define software interaction without an unexplained GUI-specific claim: "An Application Programming Interface (API) is a set of rules for communication between software components." | MDN API glossary; GitHub REST API |
| CI/CD | "A software development practice where developers regularly merge their code changes into a central repository, after which automated builds and tests are run." | Distinguish integration, delivery, and deployment instead of defining only CI. Preserve CI/CD, CI, and CD. |
GitLab CI/CD explanation; GitHub Actions concepts |
| Branch | "a parallel version of a repository that diverges from the main working project" | Explain an independent line of development and Git's commit pointer without a main-branch requirement. | Pro Git: branches |
| MkDocs | "A fast, simple static site generator that's geared towards building project documentation" | Remove subjective qualifiers and the contraction; retain MkDocs and its Markdown input. | MkDocs |
| REST API | "An architectural style for designing web services that uses HTTP requests to GET, PUT, POST, and DELETE data." | Distinguish a REST API from the REST architectural style; keep the HTTP method names as examples. | Fielding, chapter 5; HTTP semantics |
| Abbreviation include | *[CI/CD]: Continuous Integration/Continuous Deployment; *[HTML]: Hyper Text Markup Language; *[XML]: eXtensible Markup Language |
Preserve each key. Align CI/CD with both CD meanings and use the canonical HTML/XML names. | GitLab CI/CD; W3C HTML; W3C XML |
| Docker tooltip | "Platform for developing, shipping, and running applications in containers" | Use "Platform with tools to develop, distribute, and run applications in containers", which matches the revised Docker definition. | Docker overview |
pwsh tooltip |
"PowerShell Core (also known as PowerShell 7)" | Identify the executable rather than treating product names as aliases: "PowerShell 7 command-line executable". Keep the exact key and version number. | PowerShell about_Pwsh |
| LTS | "Long-Term Servicing (LTS)." | Keep the exact term, heading, anchor, abbreviation key, and existing versioned support link. Add a useful definition and a direct reference instruction. Do not substitute "Support" for "Servicing". | PowerShell support lifecycle explicitly uses Long Term Servicing |
Acceptance criteria
- Every assigned file has a recorded manual review result: changed, justified no-change, or a specific evidence-backed blocker.
- Definitions and descriptive index text use direct, present-tense en-US prose. Contribution and search procedures remain direct imperatives.
- Technical terms, all abbreviation keys, links, public names, versions, examples, and supported meanings remain correct. Factual corrections cite a canonical source.
- Existing headings and anchors remain stable where possible. Any changed target has all affected links repaired.
- Generated index regions, module-catalog content, legal text, and exact external quotations remain unchanged. No new enforcement tool or repository dependency is added.
- The draft PR records concrete before/after evidence, the full reviewed/no-change/excluded path list, and the existing checks used. It does not claim full STE conformance from automated checks.
- The result is committed and pushed in small commits to one draft PR. The PR closes only this Task upon eventual merge. It remains in draft with no merge or auto-merge request.
Technical decisions
Keep the existing reference layout, paths, front matter keys and values, heading anchors, and internal link targets. Sentence-case index headings retain their existing slugged anchors. Keep all existing glossary terms, including MkDocs and Long-Term Servicing. The glossary does not claim that MkDocs is the site's generator.
The changed Dictionary files are index.md, api.md, azure-functions.md, branch.md, ci-cd.md, cmdlet.md, docker.md, github.md, github-actions.md, lts.md, markdown.md, mkdocs.md, pipeline.md, powershell.md, pull-request.md, rest-api.md, semantic-versioning.md, template.md, workflow.md, and yaml.md. Changes remove conversational wording, passive descriptions, unsupported qualifiers, or ambiguity. Exact examples and names remain unless an active-voice rewrite preserves the example's operation.
The following Dictionary files have a final no-change result: azure.md, azure-devops.md, build-pipeline.md, container.md, devops.md, git.md, module.md, repository.md, static-site-generator.md, testing.md, version-control.md, and virtual-environment.md. Their short lookup definitions already state their purpose without change history or conversational framing. All 12 files are byte-for-byte identical to the base. A terminology pass does not require a cosmetic rewrite of every definition.
All 50 abbreviation keys and tooltip values have a manual review. The tooltip edit is limited to CI/CD, Docker, HTML, pwsh, and XML. Keep all 50 keys, their order, and the other 45 values byte-for-byte unchanged.
All other repository paths are excluded from edits. In particular, keep docs/zensical.toml, docs/content/index.md, docs/content/Modules/**, other documentation sections, workflow files, templates, native help, and linter configuration unchanged. The review does not take over framework or release proposals.
Use the existing .github/linters/.markdown-lint.yml and the zensical build --clean check from .github/workflows/Docs.yml. Enumerate Markdown filenames explicitly on Windows; the first wildcard attempt covered only the include and is not accepted as glossary validation. The corrected baseline run covers all 33 files and reports zero lint issues. Build a local copy under session artifacts so build output does not modify excluded repository paths. The unchanged baseline site build reports "No issues found".
The repository has no separate documentation-link script. Use the existing site builder's link diagnostics and inspect the built Dictionary links and anchors. Compare front matter, abbreviation keys, examples, heading anchors, and edited-path ownership against the original snapshot. Do not add a repository checker or dependency.
Result and acceptance evidence
The committed and pushed result is PSModule/Process-PSModule#567 at head e0dd865ff0973a0eef3b3a75a0fac81ff1541592. The PR Technical details contain the complete 21-path changed inventory, before/after text and source citations for each change, the 12-path no-change inventory with reasons, exclusions, commands, and results.
All 33 assigned files have a manual review result: 21 changed, 12 no-change, and none excluded from review. Every other repository path is excluded from edits. The complete local audit also records all 303 excluded tracked paths without modifying them.
| Acceptance check | Result |
|---|---|
| Direct reference prose and imperative contribution/search procedures | The original greeting, conditional introduction, rhetorical contribution question, and unexplained GUI-specific API claim are absent from source and rendered output. Procedures retain direct instructions. |
| Technical compatibility | All 31 front-matter blocks across 32 pages, all source link-target sequences, and every rendered Dictionary heading anchor are unchanged. Dictionary\index.md has no YAML front matter. Cmdlet examples, 1.2.3, the PowerShell 7 tooltip version, and the PowerShell 7.5 link are preserved. |
| Exact abbreviation interface | All 50 keys and their order are unchanged. Only CI/CD, Docker, HTML, pwsh, and XML change values; the other 45 values match the original bytes. All 50 values render as the expected HTML tooltip with the existing Markdown/snippet settings. |
| Existing Markdown check | Explicit filename enumeration covers all 33 assigned files. npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml @files passes before edits and after each coherent change. |
| Existing site checks | zensical build --clean and zensical build --clean --strict both report "No issues found" for the base and final documentation. Builds use session-artifact copies, not excluded repository paths. |
| Rendered links and external content URLs | All 32 Dictionary pages retain their heading anchors. All 96 internal article links resolve, including 35 fragment links. Both authored external content URLs return HTTP 200. |
| Committed scope and ownership | git diff --check 64ffb1d87f86bd5d487891fdb140b78385a00531..HEAD passes. Exactly the 21 owned paths change. The worktree is clean, the remote head matches, and no other open PR owns an assigned path. |
| Remote checks and review | Documentation CI and repository lint pass. Copilot approves the exact final head in review 5768355755, with no inline comments. Publish is intentionally skipped for the PR. |
No source was unavailable, and no implementation or file-ownership blocker remains. The native parent endpoint for this Task returns 404; campaign relationship maintenance is reported to the coordinator and is outside this prose delivery. #509 remains open: the base already passes the strict build with the installed builder, so this change does not claim that broader issue. Only this Task has a closing reference in the draft PR. This issue stays open until eventual merge.
Implementation plan
- Read all 33 assigned files and the pinned writing/reference sources; record original text, expected wording properties, canonical technical sources, and compatibility checks before edits.
- Establish the existing checks before edits: lint all 33 files with explicit paths and build the unchanged site in a session-artifact copy.
- Edit the glossary index and API definition; verify the focused diff, lint, and open-PR path ownership before the first small commit.
- Push that commit and open the focused draft PR with the pinned MSX PR format: PSModule/Process-PSModule#567, initial head
5f9d0d6e69fd52b838228a99ffaa8420ede63f9e. - Rewrite the remaining justified definitions in small coherent commits; check technical meaning and path ownership before each commit. Pushed commits are
88b9f46ab0d7ea8739db243ab1f374795c19b944and1d1db67f2956d035a36b140994d84cf1f625a105. Lint covers all 33 files; all 31 front-matter blocks across 32 pages, heading identities, and link-target sequences are unchanged. Cmdlet examples and version1.2.3are unchanged. - Correct the justified abbreviation tooltips; verify all keys and unchanged values before the tooltip commit. Pushed commit:
e0dd865ff0973a0eef3b3a75a0fac81ff1541592. - Complete the manual changed/no-change/excluded inventory, link/anchor review, site build, and Markdown lint; record commands and outcomes in the draft PR.
- Re-read the pushed result and current issue/PR evidence; leave the PR in draft and return its URL, head SHA, exact paths, citations, check outcomes, and remaining blockers. The final head is
e0dd865ff0973a0eef3b3a75a0fac81ff1541592; CI and the requested Copilot review pass. The issue remains open and the PR remains draft.
Activity
MariusStorhaug commentedon Nov 4, 2026
The Task now records the pinned source baseline, original text, proposed acceptance examples, all 33 reviewed paths, preliminary no-change results, and test-first steps before repository edits. Markdown lint covers all 33 assigned files with zero issues, and the unchanged site build reports no issues. Microsoft confirms Long-Term Servicing, so that exact term stays unchanged. No source was unavailable. The implementation remains limited to the assigned glossary and abbreviation paths.
MariusStorhaug commentedon Nov 4, 2026
The first coherent commit states the glossary purpose and API definition directly. Draft #567 is open at 5f9d0d6 after the focused diff, all 33 Markdown files, and open-PR ownership passed review. The issue plan now marks those two delivery steps complete. Remaining definition and tooltip edits stay within the assigned paths.
MariusStorhaug commentedon Nov 4, 2026
Pushed commit 88b9f46 records the workflow definition changes. CI/CD now distinguishes integration, delivery, and deployment. The branch and REST API definitions separate their concepts, while examples use active voice. All 31 front-matter blocks across 32 pages, heading identities, and link-target sequences remain unchanged. All 33 assigned Markdown files pass lint; no other open PR owns an assigned path. The remaining lookup definitions and abbreviation tooltips are still in progress.
MariusStorhaug commentedon Nov 4, 2026
The definition pass is pushed in commits 88b9f46 and 1d1db67. All 31 front-matter blocks across 32 pages, heading identities, and link-target sequences are unchanged. The issue now records the five exact tooltip changes and their sources before the include is edited. All 50 keys, their order, and the other 45 tooltip values remain fixed. Final site/link and unchanged-file review follow that small commit.
MariusStorhaug commentedon Nov 4, 2026
The delivery is committed and pushed in four small commits at e0dd865. Draft #567 now carries the complete changed/no-change/excluded inventory, source-backed before/after evidence, commands, and results. All 33 assigned files were reviewed; 21 change and 12 remain byte-identical. Both normal and strict site builds pass on the base and final sources, all 33 files pass Markdown lint, 96 rendered local links resolve, and all 50 tooltips render exactly. Documentation CI and repository lint pass. Copilot approves the exact final head with no inline comments. The plan is complete; this issue remains open until merge, and the PR remains draft without auto-merge. The missing native parent relationship is reported to the coordinator, not changed by this prose delivery.
MariusStorhaug commentedon Nov 4, 2026
Evidence-only correction: the 32 Dictionary pages contain 31 YAML front-matter blocks. Dictionary/index.md has no YAML front matter. The evidence now distinguishes the block count from the page count. Source head e0dd865, source scope, commits, check results, and the draft lifecycle remain unchanged. No check rerun is requested.