/technical-writing

Style Guide

A reference for capturing a distinctive voice across blog posts, essays, and professional writing.

Voice & Tone

Conversational authority. Write like you're talking to a smart friend—confident but not preachy. State opinions directly without hedging excessively. When you believe something, say it: "That's not me." or "That's just how it works."

Warm skepticism. Challenge conventional wisdom constructively. Reframe problems rather than just criticizing them. Example: "Most people treat focus like a skill to master… But that misses the fundamental truth."

First-person grounding. Anchor ideas in personal experience before expanding to broader principles. "I used to kill ideas before they had a real chance." leads to a larger point about curiosity.

Structure

Hook with a twist or question. Openings often subvert expectations or pose something worth thinking about:

• "Focus isn't what you think it is."
• "What if Matt had joined Google instead of starting WordPress?"
• "You know what I mean by vibe coding?"

Short paragraphs. Rarely more than 3-4 sentences. Often just one or two. White space is part of the rhythm.

End with punch. Closings are declarative, sometimes a single line that lands:

• "So yea, I don't vibe code."
• "Everything else is noise."
• "Fail often. Fail fast."
• "That's all."

Internal linking. Weave references to previous posts naturally, building a connected body of work: "Find something that matters to you" links to related content.

Titles

Casing: Use sentence case (capitalize only the first word and proper nouns). Title case feels more formal/traditional—fine for enterprise blogs or publications, but doesn't match your voice or the conversational tone of first-person narrative posts. Sentence case reads more naturally and is what most tech blogs are moving toward.

• ✅ "Why I stopped using feature flags"
• ✅ "I changed my mind about React Server Components"
• ❌ "Why I Stopped Using Feature Flags" (too formal)
• ❌ "I Changed My Mind About React Server Components" (too formal)

Note: This can be configured via WRITING_TITLE_CASE_STYLE environment variable (defaults to "sentence" if not set).

What to lead with: Choose one:

• Tension or insight → "Why I stopped using feature flags"
• Topic only → "Thoughts on feature flags" (usually weaker)

Specificity level: Pick based on your content:

• Specific with numbers/details → "How we cut build times from 12 minutes to 45 seconds"
• Vague/generic → "Improving build performance" (feels like clickbait)

Tone matching: Match your title style to your post type:

• Reflective piece → contemplative, personal title
• Tactical how-to → direct, action-oriented title
• Philosophical essay → thoughtful, open-ended title

Formula check: Avoid these patterns (unless you have a specific reason):

• "The ultimate guide to X"
• "X is dead"
• "Everything you need to know about X"

Conversation test: Would you actually say this to someone?

• ✅ "I changed my mind about React Server Components"
• ❌ "A paradigm shift in my React Server Components journey"

Length decision:

• Shorter (usually better, but clarity first)
• Longer (if short version is confusing)

Wordplay choice:

• Skip it (unless it genuinely lands)
• Use it (only if pun/double meaning adds value, not confusion)

Final check: The title is a promise—does the post deliver on it?

Sentence-Level

Italics for emphasis and internal voice. "Is this worth my time?" or "technically" when calling out a word.

Sentence rhythm and flow. Vary sentence length. Follow a short sentence with a longer one. Let ideas breathe. Connect related thoughts with dashes, semicolons, or conjunctions instead of hard stops: "This does X. It also does Y." → "This does X—and it also does Y." Avoid sequences of 3+ sentences that are roughly the same length. Read it aloud; if it sounds like a list, it probably is. Not every thought needs its own sentence. When two ideas are tightly linked, keep them together. Reserve short, punchy sentences for emphasis—not as the default cadence.

Active voice, present tense. Write about what is, not what was or could be. Even when reflecting on the past, bring it into the present: "Something felt different."

Content Patterns

Show the build, then the insight. Walk through a process or experience before extracting the lesson. The reader discovers alongside you.

Ask questions to the reader. Close posts with genuine invitations: "What about you?" or "Have you created any subagents lately that you've found interesting?"

Concrete before abstract. Specific tools, numbers, examples come first. Then zoom out: "Thirty minutes… Even just a few months ago, this was a nights and weekends endeavor."

Bold claims with personal stakes. Don't write detached analysis. Have skin in the game and make that clear.

Formatting

Minimal headers in short posts. For essays under 500 words, let the prose flow without section breaks.

Heading casing: Use sentence case for all headings (H2, H3, etc.) to match the conversational tone. Capitalize only the first word and proper nouns.

• ✅ "How we built it"
• ✅ "The technical details"
• ❌ "How We Built It" (too formal)
• ❌ "The Technical Details" (too formal)

Note: This can be configured via WRITING_HEADING_CASE_STYLE environment variable (defaults to "sentence" if not set).

Bold for key phrases in advice posts. When listing principles, bold the main point then explain it.

Blockquotes for external voices. When citing others, pull the quote, then respond to it.

Links as texture, not interruption. Hyperlink key concepts to related posts or sources without breaking reading flow.

What to Avoid

• Jargon for its own sake
• Excessive hedging ("I think maybe perhaps…")
• Long introductions before getting to the point
• Explaining things already written about (link instead)
• Corporate-speak or buzzwords
• Unnecessary throat-clearing

Signature Phrases & Moves

Quick Reference

The essence: direct, personal, rhythmic, and built on genuine curiosity about craft.