Add outsider-first writing rules for docs
Standing voice for strategy/research prose: plain terms on first use, trigger before action, claims first with labeled evidence underneath.
This commit is contained in:
@@ -0,0 +1,36 @@
|
|||||||
|
# Writing rules (outsider-first)
|
||||||
|
|
||||||
|
**Branch:** `planning-selfserve-audit`
|
||||||
|
**Scope:** Strategy and research docs under `docs/` (especially commercial proposals and research briefs). Complements [`CONVENTIONS.md`](./CONVENTIONS.md) (anti-duplication); does not replace it.
|
||||||
|
|
||||||
|
These rules exist so a reader with no industry background can follow the argument on the first pass.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. No insider jargon without a plain clause
|
||||||
|
|
||||||
|
On first use of a term a bakery owner would not know, explain it in one plain clause in the same sentence (or the next). Prefer ordinary words over acronyms. If you must use a short label later, introduce it once.
|
||||||
|
|
||||||
|
Examples: say “Google’s short list of three at the top of many local searches” before “3-Pack”; say “name, address, and phone” before “NAP”; say “Google Business Profile” before “GBP.”
|
||||||
|
|
||||||
|
## 2. Open every claim with the reader’s trigger
|
||||||
|
|
||||||
|
Before any product action or “we build…”, show the problem the reader feels — lost customers, wrong hours, dead phone number, AI pointed somewhere else. Action comes after the trigger. Reference voice on this branch: commits `fa98bdb` (claims for zero-insider readers) and `b859f3e` (claim 1 opens with the owner’s trigger).
|
||||||
|
|
||||||
|
## 3. Plain verbs, conversational prose
|
||||||
|
|
||||||
|
Write like a clear friend who knows the subject. Complete sentences. No throat-clearing (“the sections below keep…”, “they are the receipts”), no slogan-as-mechanism, no AI-slop padding.
|
||||||
|
|
||||||
|
## 4. Claims first, evidence underneath
|
||||||
|
|
||||||
|
Lead with the argument the outsider needs. Put tables, studies, and source labels below as support. Label evidence: practitioner-reported, vendor, primary study, or UNVERIFIED. Cite or mark BLOCKED — do not invent numbers.
|
||||||
|
|
||||||
|
## 5. One SoT per topic
|
||||||
|
|
||||||
|
Amend the existing file for a topic. Do not create sibling PLAN/CONCEPT/BRIEF twins. See [`CONVENTIONS.md`](./CONVENTIONS.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Capture
|
||||||
|
|
||||||
|
Standing outsider-first rules recorded 2026-10-01 from corrected-voice passes on the research brief (`fa98bdb`, `b859f3e`).
|
||||||
Reference in New Issue
Block a user