| 1 | # Website voice |
| 2 | |
| 3 | How codewhale.net copy is written. Companion to `docs/VOICE.md` (the |
| 4 | terminal charter); this sheet covers the marketing and docs-portal surface |
| 5 | in `web/`. Reference points: opencode.ai and pi.dev — short declarative |
| 6 | sentences, one concrete fact each, install command above the fold, providers |
| 7 | and models named rather than described. |
| 8 | |
| 9 | 1. One idea per sentence. If a sentence has a semicolon, it is two sentences. |
| 10 | 2. Lead with what it is and what it does: "an open-source coding agent for |
| 11 | your terminal", "45 providers", "MIT". Numbers come from |
| 12 | `web/lib/facts.generated.ts`; never typed by hand. |
| 13 | 3. Verbs over nouns. "It reads your code and edits files", not "code |
| 14 | inspection and file mutation under approval boundaries". |
| 15 | 4. No self-narration about honesty. Do not write "truthful", "honest", |
| 16 | "real", "evidence", "recorded", "labeled as such", "deliberately". Say the |
| 17 | fact; the reader judges. |
| 18 | 5. No internal vocabulary on marketing pages: "source candidate", "provider |
| 19 | route", "permission posture", "constitution", "law", "receipt", "ledger", |
| 20 | "dogfood", "dispatcher". Use the product's own control names when a name |
| 21 | is needed (Plan / Work / Operate, Ask / Auto-Review / Full Access). |
| 22 | 6. Name things by what the reader sees, not the mechanism: "runs on your |
| 23 | machine", "asks before it acts", "read-only", "unreleased". |
| 24 | 7. No stacked qualifiers. One hedge at most, and only when the fact needs it |
| 25 | ("usually no API key"). |
| 26 | 8. Adjectives do not carry claims. Cut "concise", "durable", "explicit", |
| 27 | "well-bounded", "practical" unless the noun cannot stand without them. |
| 28 | 9. Install is a command, not a paragraph. Show the command, then one line on |
| 29 | what it puts where. |
| 30 | 10. Provider and model names are proper nouns; keep them exact and literal |
| 31 | (DeepSeek, OpenRouter, Ollama, vLLM, SGLang). Commands, flags, paths, and |
| 32 | key names stay in code style. |
| 33 | 11. Community copy names actions a person can take today: file an issue, |
| 34 | open a pull request, translate a page. No mission statements. |
| 35 | 12. Every locale says the same thing. A copy change lands in `en` and `zh` |
| 36 | together; partial locales keep key parity and fall back for page bodies. |
| 37 |