STYLE.adoc

Editorial style — titles and headlines

Table of Contents

• News vs essay
• First-party news: omit the org
• The implied-[On] test (action titles)
• Drop surplus articles
• Is equates; as / a / process orient
• Titles that plant a question
• Attach floating modifiers
• Structure and naming
• Journalism baselines (still useful)
• Antora / docs topic titles
• Quick checklist
• Examples
• Pull request titles and summaries

Rules for news posts, blog essays, and other titled prose on this org’s public surfaces. Full philosophy: Titles as orientation (and ryanjohnson.dev).

Agents and authors both follow this document.

News vs essay

Kind	Job of the title	Default shape
News (first-party)	Name what entered the record; org is already in context	Notification / status line. Example: Instruction flows added to the repertoire. Do not prefix with HCI Nerdz … unless another actor did the thing.
News (external actor)	Name who did what	Subject + present-tense verb. Example: Antora declines live-editing
Blog / essay	Orient the reader to a claim, framing, question, or situation	Pass implied [On] … when using an action; prefer as / process / indefinite over rigid X is Y equations. Drop surplus the.

Do not write a news headline that could pass for a whitepaper section heading. Do not write an essay title that only announces “we shipped a thing� unless the piece is literally a changelog in essay clothing.

First-party news: omit the org

On this site, the reader’s attention is already contextualized to this org. Unless otherwise noted, we are the actors.

• Prefer: Instruction flows added to the repertoire

• Avoid: OrgName adds instruction flows to the repertoire

Wire-service “always name the subject� still applies when the subject is not us.

The implied-[On] test (action titles)

Whenever the title uses an action, rewrite until it reads naturally after an invisible On:

• Good: Sharing the IR, not the pixels → On sharing the IR…

• Good: Navigating by content → On navigating by content

• Awkward: Navigate by content → bare imperative

• Awkward: Navigating by the content → surplus the; overformal once On is implied

Also acceptable: noun framing Navigation by content (On navigation by content).

Drop surplus articles

Headline grammar long omits a/an/the for punch when meaning stays clear. Prefer the thinner form when the only adds formality: by content, not by the content.

Is equates; as / a / process orient

Shape	Effect
Theme is a contract	Rigid equation of two closed concepts; little room to ask “which?�
Theme as a contract	Framing — orients without closing the definition
Theming is a contract	Process/verb noun; admits behavior beyond the dictionary sense
A theme is a contract	Existential opener (“there exists a theme such that…�); invites which theme?

Prefer orientation over identity equations for abstract essays.

Titles that plant a question

• Disproof: Attention is not inventory — reader asks why not? / how not? (needs a real finding)

• Situation: When 'non-technical' products lie — places the reader in a class of events

• Identity question: What is Antora Supplemental? — matches the query people already have

Avoid commitment without a finding (dictation) and floating jargon without an object.

Attach floating modifiers

Sequence as the top-level disorients — top-level what? Prefer Sequence as top-level organization (name the object/context).

Structure and naming

• One strong idea per news item — split rejection vs shipping into cross-linked posts when both claims stand alone

• Big idea first — Reimplementing dark mode as an overlay, not burying the job under an implementation nuance

• Human names before CLI tokens — unless the invocation is the news

• Welcome posts — first news should orient: motivation, philosophy, people involved + profile links

• Soft welcomes OK when continuity with a prior surface is assumed

• Predictable slight inaccuracy is sometimes genre-normal; disorientation is the failure to fix

Journalism baselines (still useful)

• Headline present for recent events; infinitive for futures

• Prefer a verb in news (or a clear notification participle: added, ships)

• Sentence case; accuracy over cleverness

Sources: AP headline notes; reporting textbooks (verb + present); Cambridge headline grammar (article drop, present for immediacy). Orientation, as vs is, and first-party actor omission are house doctrine beyond those manuals — see the philosophy essay.

Antora / docs topic titles

Encyclopedia concept names (= Instruction flows) — no forced news verb.

Quick checklist

1. First-party news → org omitted unless another actor?

2. Action title → [On] + title sounds human? Surplus the dropped?

3. Abstract claim → as / process / a / question / when / disproof instead of rigid X is Y?

4. Modifiers attached to an object?

5. One idea per news item? Big idea first?

6. Sentence case? Orienting? Honest enough?

Examples

Context	Prefer	Avoid
News	Instruction flows added to the repertoire	OrgName adds instruction flows to the repertoire
Essay (action)	Navigating by content	Navigating by the content, Navigate by content
Essay (framing)	Theme as a contract	Theme is a contract
Essay (situation)	When the UI hides what counts	The bug is product representation
Essay (organization)	Sequence as top-level organization	Sequence as the top-level: …

Pull request titles and summaries

When opening a pull request (especially an upstream gift):

• Title — simple plain language. Orient the reviewer. Example: Make dark mode cover the preview and title bar.

• Summary / intro — inviting plain English. Lead with the human problem; short bullets for what changed; soft close inviting feedback. Tone: gift to maintainers, not a lecture.

• UI-visible changes — before/after screenshots at minimum.

Agent detail: general/pull-requests.md in dev-centr/agent-rules (org shortcut: agents/editorial/pull-requests.md).