Landing: give the last section a subject - #143
Open
adnaan wants to merge 1 commit into
Open
Conversation
"Everything else" over "The rest of the docs covers the ordinary screens." was a heading about the documentation, not about the software. It told a reader nothing they hadn't already assumed. The reason it couldn't say anything: the section held three different taxonomies. The eyebrow was a non-label, the heading described the docs, the lead listed app types (admin panels, CRUD, dashboards) and the eight links listed capabilities (uploads, pubsub, sessions, errors, CLI, client, observability, scaling). No heading summarises three subjects. The heading now names two of those capabilities and says they're here. The lead names the rest. Together they cover the grid, which is what makes the section readable as one thing. Two of the eight links contradicted it. "Shared views / Subscribe & Publish" is what the Multi-user section demonstrates, and "Forms & errors" is what the Validation section demonstrates — neither is something the wall skipped. Both references now sit inside the section that shows them off, where a reader who wants the API is already standing. Their grid slots go to two genuine gaps: auth, which the old lead named without ever linking, and navigation, which nothing on the page mentioned. One draft of the lead promised "sessions that outlive a restart". That is wrong by default: reference/session documents the SessionStore as "in-memory or Redis", and every persistence claim on that page is scoped to surviving a page refresh, not a process restart. Cut rather than qualified — the sentence did not need it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ
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.
Right, and it's worse than bland — it's a heading about the documentation rather than the software. It told a reader nothing they hadn't already assumed.
Why it couldn't say anything
The section held three different taxonomies at once:
No heading summarises three subjects, so the one there summarised none of them.
The heading now names two capabilities from the grid and answers the objection a reader actually has after scrolling through a greeting wall. The lead names the rest — sessions, navigation, scaling, and what to look at when it falls over at 3am. Together they cover the eight links, which is what makes the section read as one thing.
Two links contradicted the new heading
"Shared views / Subscribe & Publish" is exactly what the Multi-user section demonstrates, and "Forms & errors" is exactly what the Validation section demonstrates. Neither is something the wall skipped.
Both references now sit at the end of the section that shows them off, where a reader who wants the API is already standing. Their grid slots go to two genuine gaps:
/recipes/login/— the old lead said "auth" and never linked it/reference/navigate— nothing on the page mentioned itOne false claim, cut before it shipped
A draft of the lead promised "sessions that outlive a restart". Wrong by default —
reference/sessiondocuments the SessionStore as "in-memory or Redis", and every persistence claim on that page is scoped to surviving a page refresh, not a process restart. Redis-backed behavior presented as the baseline. Same failure mode as the Alpine row in #142, one section later.Verification
voice-check.sh— pass, every ceiling unchangedtinkerdown validate— 98/98, 0 errorsgo test ./e2e/— pass, 140smake sweepat desktop + iphone-14 — 196 visits, 2 flagged, both the pre-existinglarge-tabletimeout. The two new grid glosses are longer than the ones they replaced, so the two-column card grid on mobile was the risk.🤖 Generated with Claude Code
https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ