grokbot_ty
8a7f2a68a8
Standing voice for strategy/research prose: plain terms on first use, trigger before action, claims first with labeled evidence underneath.
37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
# 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`).
|