docs: editorial pass over docs/ and bun-types JSDoc - #33112
Merged
Merged
Conversation
Collaborator
|
Updated 6:20 PM PT - Jun 29th, 2026
❌ @alii, your commit fe890aa has 2 failures in
🧪 To try this PR locally: bunx bun-pr 33112That installs a local version of the PR into your bun-33112 --bun |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
This was referenced Jun 30, 2026
This was referenced Aug 13, 2026
alii
added a commit
that referenced
this pull request
Aug 14, 2026
### Problem - The docs have been through several docs-wide editorial passes that applied the same rules by hand (#28788, #33112, and #38686 a few hours after the pages it rewrote were merged), but the rules are not written down anywhere in the repo, so new pages keep reintroducing the same patterns. - `docs/README.md` still tells contributors to preview the docs with the Mintlify CLI; bun.com/docs is no longer built with Mintlify. ### Fix - Adds a "Contributing to the docs" section to `docs/project/contributing.mdx` with a "Voice" subsection: short sentences, plain words, active voice with the actor named, present tense, second person, name the subject instead of a bare "this", no "easy"/"simple"/"just"/"quick", say what to do rather than what to avoid, gender-neutral wording, descriptive link text, run every example. Adapted from the [Next.js docs contribution guide](https://nextjs.org/docs/community/contribution-guide#voice), which is credited in the text. - `docs/README.md` points at the section, and its Mintlify "Development" section is removed (it now says only that bun.com/docs is built from this directory). - Verified: `prettier --check` on both files; the link targets in the new section (`/pm/cli/install`, the Next.js URL) resolve. ### Related - #38718 adds the matching one-line pointer in `.claude/docs/landing-prs.md`. It is a separate PR so that this one only touches `docs/`, which lets CI skip the test pipeline for it. - A docs-wide pass that applies these rules to the existing pages is going up as a separate PR. Co-authored-by: Alistair Smith <hi@alistair.sh>
alii
pushed a commit
that referenced
this pull request
Aug 14, 2026
…page (#38718) ### Problem - `.claude/docs/landing-prs.md` ("Docs, types, and comments") covers verifying docs claims but says nothing about prose style, so docs PRs keep reintroducing the patterns that #28788, #33112 and #38686 removed (run-on sentences, passive voice, "will", tutorial "we", "easy"/"simple"/"just"). ### Fix - Adds one bullet to that section summarizing the voice rules and pointing at the "Voice" section that #38705 adds to `docs/project/contributing.mdx`. - Split out from #38705 because a PR whose files are all under `docs/` skips the test pipeline (`.buildkite/ci.mjs`, the "PR is only docs" check), and this file is outside `docs/`. Keeping it separate lets #38705 and the docs-wide pass stay docs-only. - Markdown only; nothing to run. The file is outside the paths `bun run prettier` formats, so the existing formatting of neighboring lines is left as is.
alii
pushed a commit
that referenced
this pull request
Aug 15, 2026
### Problem - The docs still contain a lot of prose that breaks the voice rules #38705 added to the contributing page: passive sentences with no actor ("coverage is merged by the coordinator"), sentences that chain four or five clauses with commas and dashes, "will" for present behavior, bare "This ..." sentences whose referent is unclear, tutorial "we", and "easy"/"simple"/"just". #38686 fixed this for the pages added last week; this PR does the same for the rest of `docs/`. ### Fix - Wording-only pass over every page in `docs/` (332 files read, 179 changed, 845 hunks, +1011/-966). Each hunk is one of: name the actor (Bun, the bundler, the test coordinator, you), split a run-on sentence or turn an enumeration into a list, present tense, name the subject of a bare "this"/"it", "you" instead of "we", or drop a subjective word. Net 80 fewer em dashes; no new ones. - Nothing but prose changed. Checked mechanically for every changed file against `main`: fenced code blocks byte-identical, headings identical, frontmatter identical, link targets identical (same multiset), MDX component tags identical, same number of table rows, and no inline code span added or removed. `prettier --check docs` is clean. - No claim about Bun's behavior was added, removed or changed. Every hunk got a second read specifically for that (20 hunks were tightened and 28 reverted as a result, which is why two of the 181 files touched ended up unchanged). The 37 hunks where a qualifier word (not, only, unless, except, default, ...) disappeared from the old text were checked individually; in each the condition is still stated in the new wording (for example "the next fire is not scheduled until it settles" became "Bun schedules the next fire only once it settles"). - Docs-only, so CI skips the test pipeline for this PR. This will conflict with open docs PRs that touch the same lines; the edits are sentence-level, so rebasing either side is mechanical. ### Background - The rules applied here are the ones on [the contributing page](https://bun.com/docs/project/contributing#voice) (#38705), adapted from the Next.js docs guide. Two earlier passes (#28788, #33112) removed the grep-able cases (future tense, "Note that", filler); what was left is mostly passive voice and sentence structure, which is why most hunks here rephrase a whole sentence rather than delete a word. - Things that looked factually wrong or internally inconsistent were deliberately left alone, since fixing them needs someone who knows the feature; they are listed below for follow-up. <details> <summary>Example hunks</summary> `docs/test/parallel.mdx`: > \- Coverage, JUnit XML and snapshot writes are merged by the coordinator, so ... > \+ The coordinator merges coverage, JUnit XML and snapshot writes, so ... > \- `--timings` can be passed more than once; the files are read as one table (paths that don't exist yet are skipped), and `--update-timings` writes to the **first** path. > \+ You can pass `--timings` more than once. Bun reads the files as one table and skips paths that don't exist yet. `--update-timings` writes to the **first** path. `docs/guides/process/os-signals.mdx`: one sentence carrying two events, two links and two conditions became a two-item list. `docs/project/building-windows.mdx`: the four things `--lto=on` does became a four-item list; the two reasons there is no LTO for arm64 and `--baseline` became two sentences. `docs/runtime/sqlite.mdx`: > \- Using a statement that was finalized by `close()` throws `Database has closed`, except `toString()`, which returns an empty string, and `finalize()`, which stays safe to call. > \+ Using a statement that `close()` finalized throws `Database has closed`. Two exceptions: `toString()` returns an empty string, and `finalize()` stays safe to call. </details> <!-- factual-issues -->
This was referenced Sep 2, 2026
Closed
This branch was successfully deployed
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
2 participants
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.
Summary
Editorial pass over all of
docs/**/*.mdx(322 files) and the JSDoc inpackages/bun-types/*.d.ts(20 files): ~3,200 prose fixes, net −11.9k words. Style only — this PR does not add or change any claim about how Bun behaves.What it fixes (the recurring problems in the current docs, roughly by frequency):
bun install"@param x The x, question-form summaries, copy-paste errors where a doc describes its sibling (e.g.pongdocumented asping), unfenced@exampleblocks, stale@since v10.xtags inherited from@types/nodeDeliberately not touched, so the diff stays reviewable: code inside fences (10 comment-only lines excepted), heading text (anchor targets), frontmatter titles, MDX components and link URLs, type signatures, the duplicated/forked page pairs (
runtime/file-types↔bundler/loaders,typescript×2,runtime/plugins↔bundler/plugins), and anything where the prose looked factually wrong — those need an author, not an editor, and are listed separately.Test plan
bun test test/integration/bun-types/bun-types.test.ts— 12/12 pass (the.d.tsdiff is comment-only; verified mechanically that no non-comment character changed in any declaration file)prettier --checkclean overdocs/andpackages/bun-types.mdxvsmain: code fences byte-identical, heading set unchanged, frontmatter keys/titles unchanged, link targets unchanged or resolving to an existing page, MDX component/JSX token multiset unchanged, import lines unchangedmint devspot-check of a few of the most-edited pages (runtime/module-resolution,bundler/index,pm/isolated-installs)