docs: voice pass over docs/

[robobun]

Problem

• The docs still contain a lot of prose that breaks the voice rules docs: add voice guidelines to the contributing page #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". docs(pm): make the dedupe / prune / audit fix / licenses / --filter / --catalog docs readable #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 (docs: add voice guidelines to the contributing page #38705), adapted from the Next.js docs guide. Two earlier passes (docs: improve voice #28788, docs: editorial pass over docs/ and bun-types JSDoc #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.

Example hunks

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.

[robobun]

^{Updated 5:19 PM PT - Aug 14th, 2026}

✅ @robobun, your commit 53cd56770877a79159458424cf94d674cb0e5c51 passed in Build #96932! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 38760

That installs a local version of the PR into your bun-38760 executable, so you can run:

bun-38760 --bun

[robobun]

Status: merged at 53cd567 (rebased; the two conflicts in docs/runtime/toml.mdx and docs/runtime/html-rewriter.mdx were resolved by taking main's new text).

Review comments that arrive after the merge are welcome; anything that needs a change will go into a follow-up PR.

Guidelines this applies: #38705. Pointer for reviewers of future docs PRs: #38718.

[claude]

I reviewed this PR and didn't find any bugs — every hunk I sampled across the diff is a meaning-preserving voice edit matching the #38705 rules. Because it rewrites prose across 179 pages (~845 hunks) of user-facing docs, a maintainer skim for tone would still be worthwhile before merge.

What was reviewed:

• Sampled hunks across bundler/, guides/, pm/, runtime/, test/, and project/ — all passive→active, sentence-split, or subject-naming edits with technical claims preserved.
• Checked qualifier-bearing hunks (only/unless/except/default) in cron.mdx, prune.mdx, overrides.mdx, lockfile.mdx, routing.mdx — conditions still stated in the new wording.
• Checked the enumeration→list conversions in loaders.mdx, file-types.mdx, os-signals.mdx, migrate-from-jest.mdx, building-windows.mdx, css.mdx — content unchanged.
• Spot-checked that inline code spans and link targets are unchanged in the reworded sentences.

Extended reasoning...

Overview

This PR is a wording-only voice pass over 179 files in docs/ (845 hunks, +1011/-966), applying the docs voice rules merged in #38705: name the actor instead of passive voice, split run-on sentences, present tense, name the referent of bare "this"/"it", second person instead of "we", and drop subjective words like "just"/"simple"/"easy". No source code, tests, or type declarations are touched. The PR body documents mechanical verification that fenced code blocks, headings, frontmatter, link targets, MDX component tags, table row counts, and inline code spans are byte-identical to main, and that prettier --check docs is clean. CI passes (docs-only pipeline).

Security risks

None. This touches only .mdx prose under docs/. No executable code paths, config, or dependency changes.

Level of scrutiny

Low per hunk — each is a 1-3 sentence rewording — but the aggregate is a sweeping rewrite of the public documentation's voice. I sampled broadly across the diff (bundler, guides, pm/cli, runtime API pages, test runner docs, project/contributing pages) and every hunk I read preserves technical meaning. I paid particular attention to hunks where a qualifier word moved or a clause was split off, since those are where meaning drift is most likely; in each case the condition survives in the new wording (e.g. "the next fire is not scheduled until it settles" → "Bun schedules the next fire only once it settles").

Other factors

Voice and tone across the entire docs tree is ultimately an editorial call. At 845 hunks I can't claim to have read every one, and even where meaning is preserved a maintainer may prefer specific phrasings. Given the scope — nearly every user-facing page — a human skim seems appropriate before this lands, so I'm deferring rather than shadow-approving.