# 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.