docs: add voice guidelines to the contributing page - #38705
Conversation
|
Warning Review limit reached
Next review available in: 16 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
Comment |
|
Status: merged. Docs-only ( Related:
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-only change writing down editorial conventions that prior passes (#28788, #33112, #38686) already applied by hand.
What was reviewed:
- Verified the internal link target
/pm/cli/installexists (docs/pm/cli/install.mdx). - Checked the Mintlify preview instructions match the existing ones in
docs/README.md. - Confirmed the
.claude/docs/landing-prs.mdbullet slots into the existing "Docs, types, and comments" section without disturbing neighboring bullets. - The new prose follows its own voice rules (active, present-tense, second-person, no "simple"/"just").
Extended reasoning...
Overview
This PR adds a "Contributing to the docs" section to docs/project/contributing.mdx with a "Voice" subsection codifying the editorial rules that have been applied in repeated docs-wide cleanup PRs. It also adds a pointer from docs/README.md and a one-line summary bullet in .claude/docs/landing-prs.md next to the existing docs-verification guidance. Three files touched, all Markdown/MDX, ~30 net added lines.
Security risks
None. Pure documentation prose; no code, no config, no build changes, no executable snippets beyond bun install -g mint / mint dev, which mirror the existing instructions already in docs/README.md.
Level of scrutiny
Low. This is contributor-facing documentation about writing style. It touches no runtime code, no tests, no CI config, and no type declarations. The only correctness surface is markdown rendering and link validity — the fenced code block is balanced, headings nest correctly (## then ###), and the one internal link (/pm/cli/install) resolves to an existing page.
Other factors
- The content is consistent with the repo's existing review guidance: the "run every code example" and "check option names against
main" bullets restate the adjacent "Verify every documentation claim you publish" rule already inlanding-prs.md. - The Mintlify preview commands duplicate what
docs/README.mdalready documents, so no new tooling assumption is introduced. - No prior reviews or outstanding comments on the thread beyond bot noise.
- The PR description states the link targets and prettier formatting were verified; I independently confirmed the internal link target exists.
Distills the rules the last few docs-wide editorial passes applied by hand (short sentences, active voice, present tense, second person, no easy/simple/ just, positive framing) into a Voice section on the contributing page, adapted from the Next.js docs contribution guide. docs/README.md points at it.
5fb29a3 to
4ec2b14
Compare
|
Updated 3:53 PM PT - Aug 14th, 2026
✅ @robobun, your commit ab635bc3e5de9288e40b9f867dfc4732fed5cf4c passed in 🧪 To try this PR locally: bunx bun-pr 38705That installs a local version of the PR into your bun-38705 --bun |
There was a problem hiding this comment.
LGTM — docs-only addition of voice guidelines. The inline nit about the missing .claude/docs/landing-prs.md hunk (or the PR-description claim referencing it) is worth resolving before merge, but it doesn't block the substance.
Extended reasoning...
Overview
This PR adds a "Contributing to the docs" section with a "Voice" subsection to docs/project/contributing.mdx (11 bullet points on writing style: short sentences, active voice, present tense, second person, no "easy/simple/just", descriptive link text, run examples, etc.), and adds a two-sentence pointer to it in docs/README.md. Total: +28 lines across two Markdown/MDX files. No source code, tests, config, or generated files are touched.
Security risks
None. This is prose in documentation files with no executable content beyond a three-line bash example (bun install -g mint, cd docs, mint dev) that already appears verbatim in docs/README.md.
Level of scrutiny
Low. Docs-only change with no behavioral impact and green CI. I checked that the internal link target /pm/cli/install exists (docs/pm/cli/install.mdx), that the new section's own prose follows the rules it introduces, that the ### Voice heading produces the #voice anchor referenced from docs/README.md, and that no CODEOWNERS entry covers docs/. The guidelines codify existing practice from prior editorial passes (#28788, #33112, #38686) rather than introduce new policy, so this is not a design decision requiring maintainer sign-off.
Other factors
The bug-hunting system flagged one nit: the PR description says .claude/docs/landing-prs.md gets a one-line summary, but that file is not in the diff. This is a real discrepancy between the description and what lands, but it is auxiliary — the canonical guidelines land correctly in contributing.mdx and the docs/README.md pointer is present. The fix is trivial (add the one-liner or drop the description bullet), and the inline comment already surfaces it, so it does not need to block approval.
…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.
|
|
||
| ## Contributing to the docs | ||
|
|
||
| The docs are the MDX files in `docs/` in the Bun repository. [bun.com/docs](https://bun.com/docs) is built from them. |
There was a problem hiding this comment.
🟡 The description says this section covers "how to preview them", but the landed text only says where the docs live — and commit ab635bc in this PR deletes the ## Development (Mintlify mint dev) block from docs/README.md without mentioning it in the description, so contributors now have no documented way to preview docs locally. Either add (or point to) the replacement preview workflow here, or drop "how to preview them" from the description and mention the README ## Development removal so the squash message matches the diff.
Extended reasoning...
What's mismatched
The PR description's Fix bullet says:
Adds a "Contributing to the docs" section to
docs/project/contributing.mdx(where the docs live, how to preview them) with a "Voice" subsection…
The section that actually landed at contributing.mdx:383 is one sentence:
The docs are the MDX files in
docs/in the Bun repository. bun.com/docs is built from them.
That covers where the docs live, but there is no preview workflow.
The unmentioned removal
At the same time, this PR's second commit — ab635bc "drop the Mintlify preview instructions; bun.com/docs has its own generator" — deletes the entire ## Development block from docs/README.md:
-## Development
-
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview the documentation locally:
-
-```bash
-bun install -g mint
-```
-
-Run the development server:
-
-```bash
-mint dev
-```
-
-The site is served at `http://localhost:3000`.That block was the only documented local-preview workflow anywhere in the repo. The PR description says only "docs/README.md points at the section" — it doesn't mention the removal. The description was already updated once during review (see the resolved thread about landing-prs.md moving to #38718), so keeping it accurate is clearly in scope.
Why it matters (a little)
After merge, contributors have no documented way to preview docs locally, while:
.claude/docs/landing-prs.md:55(whichCLAUDE.mdtells docs authors to read) still instructs them to "preview rendered markdown (an unbalanced fence swallows everything after it)"docs/docs.json:2still declares"$schema": "https://mintlify.com/docs.json", so it isn't obvious to a contributor that Mintlify is no longer the way to preview
So the guidance says "preview before committing", the description says "this section tells you how", and the section doesn't. The commit message for ab635bc ("bun.com/docs has its own generator") confirms the removal was intentional, which makes the description's "how to preview them" claim doubly stale.
Per .claude/docs/landing-prs.md (PR process): "The PR description is the permanent squash-commit message — keep it true" and "Every file in the diff must be explainable from the PR's stated purpose."
Step-by-step
- Contributor wants to edit docs;
CLAUDE.md→ reads Docs, types, and comments in.claude/docs/landing-prs.md. - That section says: preview rendered markdown before committing.
- Contributor looks in
docs/README.md— before this PR:bun install -g mint/mint dev/localhost:3000. After this PR: only a pointer tocontributing.mdx#voice. - Contributor follows the pointer to
contributing.mdx§ Contributing to the docs — no preview instructions there either. - Contributor greps
docs/for "preview" / "mint" — onlydocs.json's Mintlify$schemaand an unrelated font-CDN URL remain, which is more confusing than nothing.
Fix
Either of:
- Add the intended preview line to
contributing.mdx§ Contributing to the docs (whatever replaced Mintlify — the ab635bc commit message says "bun.com/docs has its own generator", so presumably a command from that generator, or a note that there is no local preview and to check the deploy preview on the PR). - Or, drop "how to preview them" from the description's parenthetical and add a line mentioning that
docs/README.md's## Development(Mintlify) block was removed, so the squash-commit message matches what actually lands.
Why this is only a nit
Nothing breaks at runtime — this is a docs/contributor-workflow gap plus a stale squash-message claim. The Voice section (the substance of this PR) lands correctly. The fix is a one-line description edit or a one-sentence addition to the new section.
### 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 -->
2 participants
Problem
docs/README.mdstill tells contributors to preview the docs with the Mintlify CLI; bun.com/docs is no longer built with Mintlify.Fix
docs/project/contributing.mdxwith 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, which is credited in the text.docs/README.mdpoints at the section, and its Mintlify "Development" section is removed (it now says only that bun.com/docs is built from this directory).prettier --checkon both files; the link targets in the new section (/pm/cli/install, the Next.js URL) resolve.Related
.claude/docs/landing-prs.md. It is a separate PR so that this one only touchesdocs/, which lets CI skip the test pipeline for it.