Skip to content

docs: trim prose across the site to cut reading time per page - #163

Merged
stijnvanhulle merged 1 commit into
mainfrom
claude/docs-validation-audit-8upeg0
Jul 19, 2026
Merged

docs: trim prose across the site to cut reading time per page#163
stijnvanhulle merged 1 commit into
mainfrom
claude/docs-validation-audit-8upeg0

Conversation

@stijnvanhulle

Copy link
Copy Markdown
Contributor

🎯 Changes

Follow-up to #162. Ran a conciseness pass across the whole site (22 parallel agents grouped by area — concepts, reference, diagnostics, kit, adapters/parsers, getting-started/guide, migration guides, AI/community docs, all 13 plugins, and the shared snippets), each grounded in a fresh read of the real source in kubb-labs/kubb and kubb-labs/plugins so a trim never outran what the agent actually understood about the code. Each group's edit was then independently checked against its own git diff before I did a final manual pass myself.

Scope, by design: this is a length/clarity edit, not a rewrite.

  • Untouched: headings (other pages link to them by #anchor), YAML frontmatter, option names/types/default values in tables, code sample logic, and VitePress directives (<!--@include:-->, <<< @/snippets/..., ::: code-group, callouts).
  • Cut: filler and hedging, throat-clearing preambles, sentences that only restate an adjacent table or code block, and repeated explanations of the same point within a page.

91 files touched, net -52 lines. Many reference/options pages were already tight (mostly tables) and got little or no change — that's intentional, the instructions explicitly say not to force a cut just to show a number.

Caught and fixed during review (6 machine-proposed edits didn't survive independent verification, plus a few incidental style slips):

  • A page's closing sentence developed a dangling modifier that reversed its own central point (guide/concepts/kit.md).
  • A migration guide's trimmed sentence contradicted the sentence right after it ("one object" vs. "the trailing options argument").
  • plugin-barrel's index.md dropped the literal output.barrel default (false) and picked up a comma splice.
  • plugin-cypress's baseURL description became a category-mismatched, garbled sentence that lost the staging/production example priming the code sample below it.
  • plugin-faker's output.path prose dropped its default value, breaking consistency with every sibling option on the same page.
  • plugin-msw's baseURL, parser, and resolver sections lost their topic sentences even though those headings are anchor-linked directly from other pages, so a reader landing mid-page no longer saw what the option does.
  • One em dash and three clause-joining semicolons introduced during condensing, fixed to match this repo's house style.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I am using USA English (serialize, color, center, canceled, analyze, license).
  • I ran the humanizer check on any new documentation I wrote.

Generated by Claude Code

Condensed 91 pages after re-reading the underlying kubb/kubb and
kubb-labs/plugins source for each area, so trims stayed grounded in how the
code actually behaves rather than just shortening sentences blind. Every
group's edit was independently re-checked against a full git diff before
landing, and I hand-reviewed the highest-impact files myself on top of that.

Cut: filler and hedging, throat-clearing preambles, sentences that only
restated an adjacent table or code block, and repeated explanations of the
same point within a page. Left untouched: headings (other pages link to them
by anchor), frontmatter, option names/types/defaults, code sample logic, and
VitePress directives (@include, code-group, callouts).

Six of the machine-proposed edits didn't survive independent verification
(a dropped default value, a couple of anchor-linked topic sentences cut from
option docs, a comma splice, a self-contradictory rewrite, and a dangling
modifier that reversed a page's central point) and were restored or
corrected by hand. A few incidental style violations introduced during
condensing (an em dash, three clause-joining semicolons) were also fixed to
match this repo's house style.
@changeset-bot

changeset-bot Bot commented Jul 19, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 9aca15c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@stijnvanhulle
stijnvanhulle merged commit 7a49002 into main Jul 19, 2026
1 check passed
@github-actions
github-actions Bot deleted the claude/docs-validation-audit-8upeg0 branch July 19, 2026 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants