From 8a7f2a68a8576b5be3e2484032a79a4efc6d1817 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Thu, 1 Oct 2026 11:50:50 -0700 Subject: [PATCH] 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. --- docs/writing-rules.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/writing-rules.md diff --git a/docs/writing-rules.md b/docs/writing-rules.md new file mode 100644 index 0000000..435e7d7 --- /dev/null +++ b/docs/writing-rules.md @@ -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`).