| 1 | # Codewhale web copy style |
| 2 | |
| 3 | Sources: UT Dallas JSOM Business Communication Center guides |
| 4 | (`refs/utd-business-communication`), `codewhale-design/DIRECTION.md` "Words", |
| 5 | `codewhale-ops/CURRENT_DECISIONS.md` §25b. |
| 6 | |
| 7 | ## Rules |
| 8 | 1. **Lead with a verb or the reader's outcome.** "Records every change", not "Receipts for every change". Résumé-style: verb, object, proof. |
| 9 | 2. **Know the reader.** A developer deciding whether to install. Say what they get, then the one next step. |
| 10 | 3. **One idea per unit.** One heading, one claim, one CTA per block. |
| 11 | 4. **Concrete over adjectives.** Name the command, the file, the mode. `codewhale exec` beats "scriptable". |
| 12 | 5. **Never overclaim.** Every claim must be true in the released build today. Check `docs/features.toml` and `docs/*.md`; if unsure, write the narrower claim. Preview and development surfaces say so. |
| 13 | 6. **Short.** Headlines ≤ 8 words, sentence case, no period unless it is two sentences. Body ≤ 2 short sentences. |
| 14 | 7. **Parallel structure.** List items share a grammatical form (all verbs, or all nouns). |
| 15 | 8. **"You", not "we" or "users".** Address the reader directly. |
| 16 | 9. **Plain English.** Read it aloud; rewrite anything that doesn't parse on the first pass. |
| 17 | 10. **Exact product vocabulary.** Plan / Work / Operate, Ask / Auto-Review / Full Access, Fleet, Runtime, `codewhale exec`, `/provider`, `/model`. |
| 18 | 11. **No public pricing. No desktop download offer.** Placeholders (`{brand}`, `{version}`, `{tag}`) stay verbatim. |
| 19 | |
| 20 | ## Slop blacklist |
| 21 | Words: seamless, powerful, unlock, leverage, empower, effortless, robust, |
| 22 | cutting-edge, journey, elevate, supercharge, revolutionize, next-generation, |
| 23 | world-class, best-in-class, game-changer, harness, delve, streamline, unleash, |
| 24 | first-class, simply, just, truly, really, very. |
| 25 | |
| 26 | Patterns: |
| 27 | - Stacked hedges ("can help you potentially", "may be able to"). |
| 28 | - "Whether you're X or Y…" openers. |
| 29 | - Rule-of-three padding: a third item added for rhythm, not content. |
| 30 | - Em-dash flourishes used for drama; use a period or colon. |
| 31 | - "Not just X, but Y." |
| 32 | - Vague tails: "and more", "and beyond", "everything you need". |
| 33 | - Throat-clearing: "Welcome to", "We're excited", "would love to hear from you". |
| 34 | - Generic headings: "What you can do with X", "Getting started with X", "Features". |
| 35 |