Skip to content

docs: fix typos, grammar, and broken code snippets in contributor docs#7298

Open
andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3:docs/fix-contributor-docs
Open

docs: fix typos, grammar, and broken code snippets in contributor docs#7298
andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3:docs/fix-contributor-docs

Conversation

@andromia3
Copy link
Copy Markdown

WHY are these changes introduced?

Cleanup pass on the contributor-facing docs under `docs/cli/`. Every change is either a broken code snippet, an install instruction that doesn't satisfy `package.json#engines`, or a grammar/typo bug. All verified against the current state of the repo.

WHAT is this pull request doing?

Broken code snippets — copy-pasting these would fail:

  • `docs/cli/troubleshooting.md` — the Vitest mocking example had `const import {functionA} from 'my-module'`. A `const` before `import` doesn't parse. Dropped the `const`.
  • `docs/cli/testing-strategy.md` — the unit-test example binds the result of `load()` to `got` and then asserts on `app.name`, but `app` isn't defined in scope. Changed to `got.name`.

Install instruction below the engine requirement:

  • `docs/cli/cross-os-compatibility.md` — the Linux contributor setup installs Node 18 via `curl -fsSL https://deb.nodesource.com/setup_18.x\`. But `packages/cli/package.json` declares `"engines": { "node": ">=20.10.0" }` and `.nvmrc` pins `v24.1.0`. A new contributor following the guide lands on Node 18 and `pnpm install` refuses to run. Bumped to `setup_24.x` to match `.nvmrc`.

Typos, missing words, and agreement bugs:

  • `get-started.md` — "might come handy" → "might come in handy"; "all the packagesusing the Typescript `tsc` tool" → "all the packages using the TypeScript `tsc` tool" (missing space + brand casing).
  • `conventions.md` — "the name must match the name of the command represent" was missing a word → "…the name of the command it represents"; "spins up an server" → "a server"; the `browser` bullet in the public-modules list was missing its `:` (other bullets in the same list use `- `foo`: For modules…`).
  • `architecture.md` — "an horizontally-distributed" → "a horizontally-distributed" (consonant sound); "boundaries that leads" → "boundaries that lead" (plural agreement).
  • `performance.md` — "code that don't map 1-to-1" → "code that doesn't map 1-to-1" (singular agreement); "As a last resource" → "As a last resort" (wrong word).
  • `testing-strategy.md` — Given/When/Then callout said "blocks, given, when, and using code comments" — "then" was missing; also "the code test" → "the test code"; heading "Github Actions" → "GitHub Actions", plus "marge" → "merge" and another "Github" → "GitHub" in the body.
  • `cross-os-compatibility.md` — "standard library work more consistently" → "standard library works" (singular agreement).

How to test your changes?

Docs-only, every change is inside a `docs/cli/*.md` file. Rendering on GitHub or in an editor previewer is enough to verify each fix.

Post-release steps

None.

Checklist

  • I've considered possible cross-platform impacts (Mac, Linux, Windows) — the `cross-os-compatibility.md` change specifically fixes a Linux-side regression relative to the `engines` field.
  • I've considered possible documentation changes — this is the docs change.
  • I've considered analytics changes to measure impact — N/A, docs-only.
  • The change is user-facing, so I've added a changelog entry with `pnpm changeset add` — `docs/cli/**` is contributor-facing, not user-facing, so no changeset.

@andromia3 andromia3 requested a review from a team as a code owner April 14, 2026 16:27
None of these change behaviour — they're all inside docs/cli/*.md
contributor-facing markdown. Each fix was verified against the
surrounding prose or against runnable code.

Broken code snippets (would fail if a contributor copy-pasted them):
- troubleshooting.md: `const import {functionA} from 'my-module'` was
  invalid syntax — a `const` before `import` doesn't parse. Dropped
  the `const`.
- testing-strategy.md: the example test did `const got = await load()`
  and then asserted on `app.name`, but `app` isn't defined in that
  scope. Changed to `got.name`, which is what the previous line bound.

Install instructions that don't satisfy the repo's engines:
- cross-os-compatibility.md: the Linux contributor setup installs
  Node 18 via `setup_18.x`, but `packages/cli/package.json` declares
  `"engines": { "node": ">=20.10.0" }` and `.nvmrc` pins v24.1.0.
  Following the old guide leaves a contributor unable to run
  `pnpm install`. Bumped to `setup_24.x` to match `.nvmrc`.

Typos and missing words that affect readability:
- get-started.md: "might come handy" -> "might come in handy".
- get-started.md: "Type-checks all the packagesusing the Typescript
  `tsc` tool" -> "packages using the TypeScript `tsc` tool". Missing
  space plus brand capitalisation.
- conventions.md: "the name must match the name of the command
  represent" was missing a word — now "the name of the command it
  represents".
- conventions.md: "spins up an server" -> "spins up a server".
- conventions.md: the `browser` bullet in the public-modules list was
  missing a colon; the neighbouring `node` and `common` bullets use
  `- \`foo\`: For modules...`, so added the colon for consistency.
- architecture.md: "an horizontally-distributed" -> "a
  horizontally-distributed" (consonant sound, no `n`).
- architecture.md: "boundaries that leads" -> "boundaries that lead"
  (plural subject agreement).
- performance.md: "code that don't map 1-to-1" -> "code that doesn't
  map 1-to-1" (singular subject agreement).
- performance.md: "As a **last resource**" -> "As a **last resort**"
  (wrong word).
- testing-strategy.md: the Given/When/Then note said "blocks, given,
  when, and using code comments" — "then" was missing from the list.
  Also "the code test" -> "the test code" (word order).
- testing-strategy.md: "Github Actions" -> "GitHub Actions" in the
  heading, plus "marge" -> "merge" and "Github" -> "GitHub" in the
  body of that section.
- cross-os-compatibility.md: "standard library work more consistently"
  -> "standard library works" (singular subject agreement).

No changeset — `docs/cli/**` isn't user-facing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant