landing-prs: point docs prose at the voice rules on the contributing page - #38718
Conversation
|
Warning Review limit reached
Next review available in: 28 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 (1)
Comment |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — one-line addition to internal review guidance.
What was reviewed:
- Bullet format and placement match neighboring lines in the "Docs, types, and comments" section.
- Cited PRs (#28788, #33112, #38686) are real; #38686 is in recent history.
- The referenced "Voice" section in
docs/project/contributing.mdxis added by companion PR #38705 (not yet on main), but the bullet inlines the full rule set so it stands on its own regardless of merge order.
Extended reasoning...
Overview
Adds a single bullet to .claude/docs/landing-prs.md under "Docs, types, and comments" summarizing the docs prose voice rules (short sentences, active voice, present tense, no tutorial "we", no "easy"/"simple"/"just") and pointing at the "Voice" section being added to docs/project/contributing.mdx by companion PR #38705. No code, no tests, no build artifacts.
Security risks
None. This is a prose addition to an internal Claude-facing guidance markdown file under .claude/docs/. It is not user-facing documentation, not compiled, not executed, and touches no runtime, auth, or crypto surface.
Level of scrutiny
Minimal. The file is internal review-notes markdown consumed only by agents/reviewers reading it. The change is +1/-0 and matches the exact bullet style of its neighbors (bold lead-in, semicolon-separated clauses, PR citations). The only thing to check is that the content is accurate and the references resolve.
Other factors
- I verified
docs/project/contributing.mdxexists; the "Voice" heading is not on main yet (it lands with #38705, per the PR description). This is a forward reference, but the new bullet restates all the rules inline, so it is not load-bearing on #38705 merging first — worst case the pointer is briefly dangling in an internal notes file. - Cited cleanup PRs check out: #38686 is
9805144fin recent history. - The PR description explains why this was split from #38705 (the
.buildkite/ci.mjsdocs-only fast path excludes.claude/), which is a reasonable process choice and not something requiring human sign-off. - No prior reviewer comments to address; bug hunting system found nothing.
### 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>
2 participants
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 docs: improve voice #28788, docs: editorial pass over docs/ and bun-types JSDoc #33112 and docs(pm): make the dedupe / prune / audit fix / licenses / --filter / --catalog docs readable #38686 removed (run-on sentences, passive voice, "will", tutorial "we", "easy"/"simple"/"just").Fix
docs/project/contributing.mdx.docs/skips the test pipeline (.buildkite/ci.mjs, the "PR is only docs" check), and this file is outsidedocs/. Keeping it separate lets docs: add voice guidelines to the contributing page #38705 and the docs-wide pass stay docs-only.bun run prettierformats, so the existing formatting of neighboring lines is left as is.