VOICE.md: labels aren't sentences, and two other lessons from #142/#143

[adnaan]

Three rules, each earned by getting it wrong on the landing first. No content changes — VOICE.md only.

Labels are not sentences

#142 added the rule that a heading ending in a period has to be one. That rule stops at headings, and I applied it one slot too far.

Eyebrows, rail links, nav items and link glosses name a topic. They don't argue. Three of them 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 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 consecutive heading rewrites failed, because no heading summarises three subjects.

This is the more useful diagnosis of the two, because the symptom presents as an unwritable heading — which invites another heading draft rather than a look at the section. Cut to one subject and the heading writes itself.

Same pass deleted a lead that enumerated the eight links directly below it, each already carrying its own gloss. A lead that lists what the layout is already showing is doing the layout's job.

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 came from one nav change: two reference links were pulled out of the capabilities grid and needed re-homing, and a trailing sentence was the lazy answer — twice. Flagged in review on #143, one as "nonsensical and doesnt mean anything".

Hang the link on the noun or API symbol the reader is already looking at, and let the paragraph keep its ending. Both of those paragraphs previously ended on an imperative, which the trailing pointer flattened.

One thing worth knowing

scripts/voice-check.sh walks content/ only, so this file is not checked against its own rules — despite saying it applies to itself. The additions here were checked by hand against the claudism list, the passive regex, triadic negation and exclamations: all clean.

Not proposing to widen the checker's scope in this PR; VOICE.md and README.md are a different kind of document from a content page and would need their own ceilings.

🤖 Generated with Claude Code

https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ