docs: trim prose across the site to cut reading time per page - #163
Merged
Conversation
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.
|
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
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.
🎯 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/kubbandkubb-labs/pluginsso a trim never outran what the agent actually understood about the code. Each group's edit was then independently checked against its owngit diffbefore I did a final manual pass myself.Scope, by design: this is a length/clarity edit, not a rewrite.
#anchor), YAML frontmatter, option names/types/default values in tables, code sample logic, and VitePress directives (<!--@include:-->,<<< @/snippets/...,::: code-group, callouts).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):
guide/concepts/kit.md).plugin-barrel'sindex.mddropped the literaloutput.barreldefault (false) and picked up a comma splice.plugin-cypress'sbaseURLdescription became a category-mismatched, garbled sentence that lost the staging/production example priming the code sample below it.plugin-faker'soutput.pathprose dropped its default value, breaking consistency with every sibling option on the same page.plugin-msw'sbaseURL,parser, andresolversections 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.✅ Checklist
Generated by Claude Code