--- name: joel-writing-style description: "Joel's writing voice and style guide for joelclaw.com content. Use when writing, editing, or reviewing any blog post, essay, book chapter, or prose content for joelclaw.com. Also use when asked to 'write like Joel,' 'match Joel's voice,' 'draft a post,' 'write content for the blog,' or 'review this for voice.' This skill captures Joel's specific writing patterns derived from ~90,000 words of published content spanning 2012–2026. Cross-reference with copy-editing and copywriting skills for marketing-specific copy." --- # 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](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](url)." - ✅ "We partnered with [Dan Abramov and Maggie Appleton](url) to help produce their online course." - ❌ "[Click here](url) 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 - 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. 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 | Never | Instead | |---|---| | "Leverage," "utilize," "synergize," "facilitate" | "Use," "help," "make" | | "In this post, I will explore..." | Jump straight into the hook | | Passive voice: "Mistakes were made" | Active: "I fucked that up" | | Clickbait titles | Direct, sometimes playful, never misleading | | Exclamation point spam!!!! | Rare. Maybe one per post. Let the words do the work. | | "Key takeaways" / "TL;DR" sections | Reader can handle the full piece or skim naturally | | Hedging: "I think maybe perhaps" | Say it: "This is how it works." | | Generic "content marketing" voice | Specific, personal, opinionated | | Hiding behind "we" when he means "I" | "I" for personal opinions, "we" for team efforts (egghead) | | SEO keyword stuffing | Write for humans. Search follows substance. | | Attribution-free idea theft | Names and links for every borrowed concept | --- ## 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.