Plain words
Read before showing a draft. Scan it for the patterns below, then rewrite. Keep the meaning and every qualifier ("usually", "for admins only"). When a fix makes a sentence worse, fix it another way or leave it.
Words
- AI vocabulary: additionally, crucial, delve, enhance, foster, garner, interplay, intricate, landscape, pivotal, robust, seamless, showcase, tapestry, testament, underscore, vibrant. Use the plain word, or cut it.
- Fancy verbs for "is": "serves as", "stands as", "boasts", "features". Say "is" or "has".
- Long words for short ones: utilize or leverage (use), facilitate (help), numerous (many), in the event that (if), in order to (to), due to the fact that (because). Delete "it is important to note that".
- Metaphor nouns: substrate, wedge, vector, surface (as in "API surface"), bedrock, north star, flywheel, ratchet, endgame, paradigm. Name the concrete thing: the base, the way, the public methods, a limit that only goes down.
- "Simply", "easy", "just", "quickly" in steps. If it were easy, the reader wouldn't need the steps.
- One name per thing: don't rotate synonyms for variety. A reader who sees two names assumes two things.
Sentences
- Say what it does, not how it feels. "Types that follow your schema" becomes "a column rename fails the build". If the sentence would fit another project's docs unchanged, it says nothing about this one; cut it.
- State the point. Drop "not just X, but Y" and "it's not X, it's Y".
- Cut "-ing" tails that add a vague benefit: "..., ensuring reliability", "..., highlighting the need". Say the fact, or delete the tail.
- One hedge at most. "Could potentially possibly" becomes "may", or the fact.
- Replace the adverb with the number or a stronger verb. "Significantly faster" becomes "41 ms to 33 ms at p50".
- No forced groups of three. Use the number of items there really are.
- Keep "only" and "not" next to the word they change. "Only fails on retry" and "fails only on retry" say different things.
- Make "it", "this" and "they" point at one obvious thing. Repeat the noun when in doubt.
- Whole sentences. Keep the articles and verbs. No arrows, slashes ("and/or", "a/b"), "(s)" plurals, or abbreviations the reader must decode.
- Mix lengths. Split a sentence that carries two thoughts, and keep a long one that carries one with its condition.
Formatting
- Bold a lead-in only when it names the item and new detail follows. Never "Performance: Performance improved".
- Headings in sentence case, saying the point when they can ("Run the migration first", not "Migration").
- No em dashes; use a period or a comma. Straight quotes, not curly ones. No decorative emojis.
- Link text says where the link goes. Never "click here".
Chat phrases
Remove "I hope this helps", "Let me know if...", "Great question", "Certainly!", "You're absolutely right", and closing lines like "the future looks bright". End on the fact or the open question.