From 4ecab9b84ef77290ede380a6b3b96d907903bbae Mon Sep 17 00:00:00 2001 From: Adnaan Badr Date: Sun, 23 Aug 2026 11:54:40 +0000 Subject: [PATCH] docs(voice): labels aren't sentences, and other lessons from #142/#143 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three rules, each earned by getting it wrong on the landing first. **Labels are not sentences.** #142 added the rule that a heading ending in a period has to be one. That rule stops at headings. Applying it to the slots around them — eyebrows, rail links, nav items, link glosses — produced "What the wall skipped", which reads as a sentence fragment doing rhetorical work when the slot wanted a name. It took two attempts on each of three labels before they landed on something plain. The test: read the label with the page hidden and see whether it says what's in the section. **If the heading won't come, the section is the problem.** The landing's last section held three subjects, so three consecutive heading rewrites all failed. No heading summarises three subjects. This is the more useful diagnosis, because the symptom shows up as an unwritable heading, which invites more heading drafts rather than a look at the section. **A pointer bolted onto a finished paragraph.** Both instances came from the same nav change: two reference links were pulled out of a capabilities grid and needed re-homing, and a trailing sentence was the lazy answer twice. Both flagged in review, one as "nonsensical and doesnt mean anything". Noting for whoever reads this next: voice-check.sh walks content/ only, so this file is not checked against its own rules. The additions above were checked by hand. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ --- VOICE.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/VOICE.md b/VOICE.md index 14ff931..91f1089 100644 --- a/VOICE.md +++ b/VOICE.md @@ -69,6 +69,13 @@ back on every rewrite because it reads as thoughtful: Say the plain thing. "load-bearing" is "this line is what makes it work". "surfaces an error" is "shows the error". "primitives" is usually "functions". +**A pointer bolted onto a finished paragraph.** "The pubsub reference has the +topic rules and the ACL in full." "…and the error handling reference has the +rest." Both were links that needed a home after a nav change, and a trailing +sentence was the lazy place to put them. Hang the link on the noun or the API +symbol the reader is already looking at, and let the paragraph keep its ending — +usually an imperative, which a trailing pointer flattens. + **The rhetorical reversal.** A contrast whose second half exists only to make the sentence land: @@ -134,6 +141,38 @@ When they drifted, all three were vague at once ("What's going on" / "What's going on" / "The parts of that worth a second look.") and none named the contents. +## Labels are not sentences + +That rule is about headings. It stops at the slots around them — the eyebrow +over an h2, the rail link pointing at it, a nav item, the gloss under a link. +Those name a topic. They don't argue, concede, or set anything up. + +Three on the landing took two attempts each before landing somewhere plain: + + Everything else -> More capabilities + What the wall skipped -> More capabilities + What's going on -> Line by line + +Every attempt in between was a phrase doing rhetorical work — meeting an +objection, or naming a gap. The slot wanted a name. A +reader scanning the rail is asking whether the thing they want is in there, and +only a name answers that. + +The test: read the label with the page hidden. If it doesn't say what's in the +section, it's decoration. + +## If the heading won't come, the section is the problem + +The landing's last section carried three subjects at once — a heading about the +documentation, a lead listing app types, and eight links listing capabilities. +Three rewrites of the heading failed in a row, because no heading summarises +three subjects. + +Cut the section to one subject first; the heading writes itself afterwards. The +same pass also deleted a lead that enumerated the eight links sitting directly +below it, each of which already carried its own gloss. A lead that lists what +the layout is already showing is doing the layout's job. + ## A comparison table must concede Every row of the landing's comparison sat under a neighbour's name and described