Rewrote the 3.2 docs pages for readability - #21
Merged
Conversation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The reworded comments put bare apostrophes inside single-quoted demo strings, which 500'd /framework/docs/3.2/chart. Reworded without apostrophes; the docs request spec is green again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Its documented format uses the em-dash as the field separator between a term and its transcription notes; it is not prose copy. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The copy style spec caps section paragraphs at three sentences; seven of the plain-words rewrites had grown to four. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
One page now says one thing once: the themes page keeps a single screen picker tip, the tautological Dark paragraph and the demo self-narration are gone, and negation-first openers state the positive fact instead. Also merged sass_build's duplicate data-URI sections, dropped outline's two paragraphs that pre-told their own subsections, and removed the generic sentence under Where This Applies. The rule is in the style guide as Earn the paragraph. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…d heading case Five reviewer agents read every PR page top to bottom against the style bar. This final batch covers the sass and reference clusters, the page subtitles in PAGE_DESCRIPTIONS, and Title Case for the section headings, matching the mature corpus. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Intros now say what a thing is for, not what it is technically: themes are a simple way to visually customize a plugin, theme authoring explains slots, the overview names all 3.2 features evenly. Charts guidance tells readers to use TRMNLCharts and what they get. Dark mode left the headline positions. The stale palette-image claims are gone (colors dither down to the panel's inks where needed, exact on full color). The open source page links the GitHub repo prominently, and the theme contract list now reads as actions. The bar is in the style guide as Write for the reader, not the framework. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Reader-purpose framing throughout: card blurbs and section leads say what a thing is for, TRMNLCharts leads with what you get, and the theme contract gained the chart-colors bullet it was missing. Dark mode left every remaining headline position; it survives only in watch() trigger lists, dark-mode notices, and sections that document it. Factual fixes verified against source: the shipped-themes claim matched to dark-theme.scss, outline covers full-color displays, the last palette-tile and pattern-image sentences are gone, and applyHighchartsAxisPaint got its real signature. Reader gaps closed: who writes the device class, where theme stylesheets come from, clone links on the build and contributing pages, the pattern-fill module requirement, and data-chart-series-count. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Both shipped in the 3.1.5 bundle but the 3.2.0 release notes carry them as 3.2 features, and each has its own section on the overview page. The intro named Fluid Mashups, their 3.1.5 sibling, but skipped them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The release notes call it the most impactful part of 3.2, but the overview page never mentioned it. It now opens the page content and the intro, linking the repository and the two contributor guides. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
The 3.2 docs pages read like spec sheets: long sentences, stacked framework vocabulary, mechanism before meaning. This PR rewrites them so a first-time reader can follow them, without changing what they document.
Scope: the 19 pages added since the core 3.1.6 sync point, the three v3 guide pages (files predate the sync, but their content was rewritten for 3.2), the shared intro paragraphs in
framework_intro_paragraphs(app/helpers/framework_helper.rb), and a second wave over the 3.2-era copy on pages that predate 3.2.The bar, now also in the docs style guide (
.claude/skills/write-docs/SKILL.md, "Plain words first"): open in everyday words, introduce a framework term only where the reader acts on it, outcome before mechanism, no clause chains, and say every sentence aloud to someone who has never read the source.Checklist
Intros
framework_helper.rb)Themes
Guides
Rendering
Paint API
Sass
Reference and meta
Second wave (pages that predate 3.2; only their 3.2-era copy was rewritten, found by diffing against the core 3.1.6 sync commit; the frozen 3.0/3.1 tracks stay untouched)
Verification: the docs request spec and helper spec pass (135 examples), and no touched file contains an em-dash.
Also carries the ZERO.md vocabulary file and its .gitignore entry over from the working tree on main.
🤖 Generated with Claude Code