113 lines
4.4 KiB
Markdown
113 lines
4.4 KiB
Markdown
# Writing Guidelines
|
|
|
|
## Sentence structure
|
|
|
|
## Voice and tone
|
|
|
|
- Write like humans speak. Avoid corporate jargon and marketing fluff.
|
|
- Be confident and direct. Avoid softening phrases like "I think," "maybe," or "could."
|
|
- Use active voice instead of passive voice.
|
|
- Use positive phrasing—say what something _is_ rather than what it _isn't_.
|
|
- Say "you" more than "we" when addressing external audiences.
|
|
- Use contractions like "I'll," "won't," and "can't" for a warmer tone.
|
|
|
|
## Specificity and evidence
|
|
|
|
- Be specific with facts and data instead of vague superlatives.
|
|
- Back up claims with concrete examples or metrics.
|
|
- Highlight customers and community members over company achievements.
|
|
- Use realistic, product-based examples instead of `foo/bar/baz` in code.
|
|
- Make content concrete, visual, and falsifiable.
|
|
|
|
## Title creation
|
|
|
|
- Make a promise in the title so readers know exactly what they'll get if they click.
|
|
- Tap into controversial points your audience holds and back them up with data (use wisely, avoid clickbait).
|
|
- Share something uniquely helpful that makes readers better at meaningful aspects of their lives.
|
|
- Avoid vague titles like "My Thoughts On XYZ." Titles should be opinions or shareable facts.
|
|
- Write placeholder titles first, complete the content, then spend time iterating on titles at the end.
|
|
|
|
## Banned words
|
|
|
|
- `a bit` → remove
|
|
- `a little` → remove
|
|
- `actually/actual` → remove
|
|
- `agile` → remove
|
|
- `arguably` → remove
|
|
- `assistance` → "help"
|
|
- `attempt` → "try"
|
|
- `battle tested` → remove
|
|
- `best practices` → "proven approaches"
|
|
- `blazing fast/lightning fast` → "build XX% faster"
|
|
- `business logic` → remove
|
|
- `cognitive load` → remove
|
|
- `commence` → "start"
|
|
- `delve` → "go into"
|
|
- `disrupt/disruptive` → remove
|
|
- `facilitate` → "help" or "ease"
|
|
- `game-changing` → specific benefit
|
|
- `great` → remove or be specific
|
|
- `implement` → "do"
|
|
- `individual` → "man" or "woman"
|
|
- `initial` → "first"
|
|
- `innovative` → remove
|
|
- `just` → remove
|
|
- `leverage` → "use"
|
|
- `mission-critical` → "important"
|
|
- `modern/modernized` → remove
|
|
- `numerous` → "many"
|
|
- `out of the box` → remove
|
|
- `performant` → "fast and reliable"
|
|
- `pretty/quite/rather/really/very` → remove
|
|
- `referred to as` → "called"
|
|
- `remainder` → "rest"
|
|
- `robust` → "strong"
|
|
- `seamless/seamlessly` → "automatic"
|
|
- `sufficient` → "enough"
|
|
- `that` → often removable, context dependent
|
|
- `thing` → be specific
|
|
- `utilize` → "use"
|
|
- `webinar` → "online event"
|
|
|
|
## Banned phrases
|
|
|
|
- `I think/I believe/we believe` → state directly
|
|
- `it seems` → remove
|
|
- `sort of/kind of` → remove
|
|
- `pretty much` → remove
|
|
- `a lot/a little` → be specific
|
|
- `By developers, for developers` → remove
|
|
- `We can't wait to see what you'll build` → remove
|
|
- `We obsess over ___` → remove
|
|
- `The future of ___` → remove
|
|
- `We're excited` → "We look forward"
|
|
- `Today, we're excited to` → remove
|
|
|
|
## Avoid LLM patterns
|
|
|
|
- Replace em dashes (—) with semicolons, commas, or sentence breaks.
|
|
- Avoid starting responses with "Great question!", "You're right!", or "Let me help you."
|
|
- Don't use phrases like "Let's dive into..."
|
|
- Skip cliché intros like "In today's fast-paced digital world" or "In the ever-evolving landscape of."
|
|
- Avoid phrases like "it's not just [x], it's [y]."
|
|
- Avoid self-referential disclaimers like "As an AI" or "I'm here to help you with."
|
|
- Don't use high-school essay closers: "In conclusion," "Overall," or "To summarize."
|
|
- Avoid numbered lists in cases where bullets work better.
|
|
- Don't end with "Hope this helps!" or similar closers.
|
|
- Avoid overusing transition words like "Furthermore," "Additionally," or "Moreover."
|
|
- Replace "In conclusion" with direct statements.
|
|
- Avoid hedge words: "might," "perhaps," "potentially" unless uncertainty is real.
|
|
- Don't stack hedging phrases: "may potentially," "it's important to note that."
|
|
- Don't create perfectly symmetrical paragraphs or lists that start with "Firstly... Secondly..."
|
|
- Avoid title-case headings; prefer sentence casing.
|
|
- Remove Unicode artifacts when copy-pasting: smart quotes ("), em-dashes, non-breaking spaces.
|
|
- Use `` instead of ''.
|
|
- Delete empty citation placeholders like "[1]" with no actual source.
|
|
|
|
## Punctuation and formatting
|
|
|
|
- Use Oxford commas consistently.
|
|
- Use exclamation points sparingly.
|
|
- Sentences can start with "But" and "And"—but don't overuse.
|
|
- Use periods instead of commas when possible for clarity.
|