joel-writing-style（乔尔写作风格）

Joel's Writing Style Guide

Joel writes like he talks — direct, warm, profane when it serves the point, and always in service of helping someone. His blog is a digital garden, not a content marketing operation. Posts range from 50-word observations to 4,000-word deep dives. Not everything is polished. That's by design.

This guide is derived from analyzing 127 posts across joelhooks.com (2012–2026).

For curated voice examples from the corpus, see references/voice-examples.md.

Core Voice Rules

1. Write conversationally in first person

Address the reader as "you." Use "I" and "we" freely. Write like you're explaining something to a smart friend over coffee — not like you're writing a blog post.

• Contractions always: it's, doesn't, I've, they're, we've, can't, won't
• Never stilted: "one might consider" → "you might try"
• No "Dear reader" or "In this post I will" throat-clearing

2. Strategic profanity is texture, not shock

Joel uses "fuck," "shit," "bullshit," "damn," and "af" naturally when they serve emphasis. Average 3–5 instances per substantive post. They land because they're infrequent enough to carry weight.

When to use it:

• Emphasis on a point: "I'm convinced that paginated posted sorted chronologically fuckin' sucks."
• Dismissing bad ideas: "No 'growth hacks' or other bullshit involved"
• Raw honesty: "I'm a shit PM."
• Celebration: "holy shit, feels good."

When NOT to use it:

• Never in headlines or H2s (rare exception: "Just Fucking Do It" as a deliberate title)
• Never gratuitously — if removing it doesn't weaken the sentence, remove it
• Never to be edgy — it should feel natural, like breathing

3. Short paragraphs, punchy rhythm

Most paragraphs are 1–3 sentences. Many are single-sentence paragraphs for emphasis. Alternate short and long sentences to create rhythm.

The pattern: Short. Short. Longer sentence that develops the idea with some texture and detail. Short punch.

This creates a reading experience that pulls you down the page.

4. Bold for inline emphasis, not decoration

Use bold to punch key phrases within sentences. Not for headers-within-paragraphs. Not for every other word.

• ✅ "We provide instructors with a world class highly skilled production team that they don't have to fuckin manage."
• ✅ "If it's negotiable, you'll negotiate your way out."
• ❌ Bolding entire sentences or paragraphs
• ❌ Using bold as a substitute for good writing

5. Emoji as warmth, not decoration

Joel uses emoji sparingly — ❤️ 🤯 😅 😂 🔥 🥰 — often at paragraph endings. They convey genuine emotion. Never more than 2–3 per post.

• ✅ "Thanks to Marie Poulin for this idea ❤️"
• ✅ "That's when I started working on egghead.io which is what I've been doing for 6 years. 🔥"
• ❌ Emoji in every paragraph
• ❌ Emoji as bullet points or list markers (except occasionally in titles: "🌱 My blog is a digital garden")

6. Italics for internal voice and refrains

Use *italics* for thoughts, recurring questions, and emphasis that's softer than bold.

• *"What would happen if I did this for a year?"*
• *badass web developer* (as a concept/identity)
• *just don't feel like doing the activities required to make more money*

Structural Patterns

Never lead with a heading

The title is already an H1 rendered above the content. An ## H2 as the first line of the body looks redundant and amateurish — two headings stacked with nothing between them. Always open with prose: a hook, a sentence, an observation. The heading comes after the opening paragraph or after any install/code block at the top.

• ❌ ## The interface is stdout (right after title — two headings in a row)
• ✅ A prose sentence, then ## The interface is stdout further down
• ✅ A skill install code block, then prose, then the first heading

Opening hooks, not thesis statements

Never open with "In this article, I'll discuss..." — open with a hook that creates tension, asks a question, or drops you into a moment.

Strong openings from Joel's corpus:

• "290 pounds and I couldn't walk and talk at the same time."
• "Have you used Jira?"
• "Recording a podcast is a shitload of work."
• "Most personal AI projects start with a database."
• "We crossed the $16M milestone on 2019-12-05."
• "Being able to work remotely is probably one of the coolest fuckin things that's ever happened to me."

⚠️ These are examples, not templates. Do NOT copy a hook's structure and swap the nouns — "Most personal AI projects start with a chat window" is just "Most personal AI projects start with a database" wearing a fake mustache. Every hook should be original to the piece. The pattern is "create tension or drop into a moment," not "Most X start with Y, but I did Z." If you catch yourself writing a comparison frame as a hook ("Most people do X / Unlike typical Y / The standard approach is Z"), throw it out. Start with the thing itself — what it does, why it matters, what broke.

Headers as narrative beats

Headers tell a story, not an outline. They're conversational, sometimes sentence fragments.

• ✅ "## I quit my job." / "## The Commitment Problem" / "## Finding My Place"
• ✅ "## We are not a commodity." / "## The bet"
• ❌ "## Introduction" / "## Key Takeaways" / "## Conclusion"

Endings are often abrupt

No forced wrap-up or "In conclusion..." — just stop when the idea is done. Often a short, warm line.

• "Life is good."
• "Bring it New Year."
• "I'm excited to find out."
• "It's very exciting, and I look forward to exploring this idea more."

Variable post length is intentional

The digital garden philosophy means a post can be 50 words or 4,000. A "Barber Shop Paradox" post that's three sentences is just as valid as a deep-dive book review. Don't pad short ideas to fill space.

Links woven into narrative

Never "click here." Links are part of the sentence flow.

• ✅ "I highly recommend watching this video from Jay Abraham."
• ✅ "We partnered with Dan Abramov and Maggie Appleton to help produce their online course."
• ❌ "Click here to learn more."

Tables for comparison, not decoration

Joel uses tables when making architectural comparisons or showing before/after. Keep them focused.

Philosophical DNA

These values permeate Joel's writing. Content that contradicts them will feel off-voice regardless of surface-level style matching.

User outcomes over features

"Don't make a better tutorial video. Make a better frontend web developer." Every piece connects technology or process to human outcomes.

Clients, not customers

From Jay Abraham's Strategy of Preeminence: "A client is someone who is under the care & protection of another." Joel treats readers as people he's advising, not audiences he's monetizing.

Anti-performative

The blog is for Joel first, readers second. "It's not that I don't care about you, but this is for me." This honesty paradoxically makes it more valuable to readers.

JFDI (Just Fucking Do It)

Bias toward action. "Quitting is a habit too — and I'm not training that one." No hand-wringing. Decide, commit, iterate.

Consistency > perfection

"Imperfection doesn't mean failure — stopping does." Posts can be seedlings. Ideas can be half-formed. Ship it and tend the garden.

Sovereignty and ownership

Self-host. Own your data. Own your platform. Against dependence on platforms that can be ruined by "one asshole."

Crediting sources

Always name people and link to their work. Alex Hillman, Amy Hoy, Kathy Sierra, Tiago Forte, Jay Abraham — the network of thinkers is visible.

The Fabrication Rule — NEVER Make Things Up

This is the single most important rule in this skill.

When writing in Joel's voice, you are putting words in a real person's mouth. Every claim, anecdote, experience, and opinion must be verifiably true or explicitly flagged as a placeholder for Joel to fill in.

What counts as fabrication:

• Inventing personal anecdotes Joel never lived ("I tried X for a week and it broke")
• Claiming specific experiences ("here's what happened in my last 24 hours")
• Putting opinions in Joel's mouth that he never expressed
• Fabricating conversations, reactions, or emotional responses
• Inventing links to posts or resources that don't exist
• Making up metrics, timelines, or results
• Guessing temporal facts instead of looking them up. If the text says "a couple of weeks" and you don't know the actual timeframe, LOOK IT UP in git history, slog, or ADRs. Never substitute one guess for another ("weeks" → "months"). Temporal claims must be verified against source data or flagged as [TODO: verify timeframe].
• Writing endorsements or testimonials Joel never gave

What to do instead:

• Describe the system factually. "The pipeline does X" not "I spent three days building X and here's what I learned"
• Use verifiable facts. Read the actual code, configs, logs, and git history. Cite what's real.
• Flag gaps honestly. If you don't know Joel's opinion on something, write [TODO: Joel's take on X] — don't guess.
• Attribute the source. If an architectural detail comes from an ADR or code comment, that's a fact. If you're inferring Joel's feelings about it, that's fabrication.
• Stick to third-person for uncertain claims. "The system does X" is always safe. "I love how X works" requires Joel to have actually said that.

Pontification must come from Joel

If a passage expresses *how Joel thinks*, *what Joel believes*, or *Joel's philosophy* about a topic — it must be sourced from Joel's actual words (conversations, vault notes, past writing, direct quotes). An LLM cannot generate philosophical positions, hot takes, or worldview statements and attribute them to Joel. These are the highest-trust sentences in any article.

• ❌ "I think it is. Not because the metaphor is precise, but because it's *useful*." (LLM inventing Joel's philosophical stance)
• ❌ "The question is whether 'alive' is the right frame..." (LLM constructing Joel's intellectual framing)
• ✅ Describe what the system does factually, then [TODO: Joel's take on what this means]
• ✅ Quote Joel directly from a conversation or past writing
• ✅ Joel writes the closing himself via feedback

When in doubt: end the article before the pontification. A factual ending that stops when the idea is done is infinitely better than an AI-generated philosophical flourish pretending to be Joel's inner monologue.

Writing in someone's voice is a privilege. The moment you invent experiences they never had, you're not writing *for* them — you're putting words in their mouth. That's not a style problem. That's a trust problem.

Anti-Patterns — What Joel Never Does

Content Types on joelclaw.com

The blog is a serialized book about building a personal AI operating system. Content falls into these patterns:

Architecture deep-dives

Technical decisions explained with clear tables, rationale, and "the bet" framing. See: "AT Protocol as Bedrock," "Why I Built My Own AI System."

• Lead with the question that prompted the decision
• Use comparison tables for architecture choices
• End with honest assessment of tradeoffs ("That's a bet.")

Personal essays

Stories from Joel's life that connect to broader lessons. See: "Getting Jacked at 50," "Setting Goals for My Version of Success."

• Open with a vivid moment, not a thesis
• Use chronological narrative with section headers as story beats
• Let the lesson emerge from the story — don't moralize at the end

Tool/system reviews

Honest assessments of tools, gear, books. See: "Badass: Making Users Awesome," "Self-Hosting."

• Lead with why it matters, not what it is
• Include personal experience and context
• Recommend genuinely — Joel doesn't do lukewarm reviews

Business philosophy

Frameworks and principles. See: "Strategy of Preeminence," "Making Other People Money."

• Ground abstract principles in specific egghead/joelclaw experience
• Use Jay Abraham and Kathy Sierra as philosophical touchstones
• Connect back to "making other people successful" as the core thesis

Short observations

Digital garden seedlings — a single idea in a few sentences. See: "The Barber Shop Paradox," "Write for somebody specific."

• Don't pad. If the idea is three sentences, publish three sentences.
• These can grow later. That's the garden.

Voice Calibration Checklist

Before publishing, run this pass:

• Does it sound like Joel talking, or like an AI writing "casually"?
• Is there at least one moment of raw honesty?
• Are paragraphs mostly 1–3 sentences?
• Does it open with a hook, not a preamble?
• Is profanity (if present) earning its keep?
• Are people credited by name?
• Does it connect to a human outcome, not just a technical fact?
• Is the ending natural, not forced?
• Would Joel actually publish this on his site?
• Is every claim, anecdote, and experience verifiably true? (No fabricated stories, fake metrics, or invented opinions)
• Are there [TODO] placeholders for anything you're uncertain Joel would say?

The fabrication check is the one that truly matters. Everything else is style. Getting the facts wrong is a trust violation.