programming-essay

# Writing essays that outlive their stack

The great programming essays do one thing: they give the reader a handle
they didn't have before. *Leaky abstractions.* *Innovation tokens.* *The
kingdom of nouns.* *Worse is better.* *No silver bullet.* Ten years later
the language is gone but the phrase is still in your head. That is the
job. Everything else in this file serves it.

If you find yourself writing "in this post we will explore…" you are not
yet writing an essay. You are warming up. Cut the warm-up.

## The six moves

**1. Name the thing.** Coin a handle readers can reuse. Spolsky didn't
invent leaky abstractions, he named them. McKinley didn't invent "don't
add tech for fun," he called it an innovation token. The name is the
durable export. Before you start, ask: what am I naming? If nothing, the
essay isn't ready.

**2. Commit to a thesis inside the first three paragraphs.** Not teased.
Not hedged. The reader should know what you believe and be able to argue
with you by the time they're scrolling. Essays that survey the landscape
before taking a side are read once and cited never.

**3. If you pick a metaphor, ride it.** Yegge's medieval kingdom is not
decoration — it is the argument. Nystrom sustains *what color is your
function* for 4,000 words and never breaks. Half-committed metaphor is
worse than none. Either your whole essay lives in the metaphor's world or
the metaphor doesn't belong.

**4. Specifics, always.** Not "a common pattern in enterprise Java" —
name the class. Not "a popular framework" — name it, version it, link
the commit. Concrete detail is the smell of someone who has actually been
there. It cannot be faked and AI cannot fake it.

**5. Pull from outside the field.** Graham pulls from painting. Brooks
from theology. Norvig's *Teach Yourself Programming in Ten Years* works
because it's built on music pedagogy, not software. The outside reference
is how an essay escapes its era — React will not exist in 2040, but the
analogy will still read.

**6. Write toward one tattooable sentence.** *"All non-trivial
abstractions, to some degree, are leaky."* *"Organizations ship their org
chart."* *"Worse is better."* Every essay that's still cited has a line
you could put on a shirt. Know which sentence of yours that is before you
publish. If you can't find it, the essay hasn't earned the draft yet.

## Voice

**Do:**

- First person, confident, specific.
- Strong opinions stated strongly — then defended, not softened.
- Pull your examples from code that actually exists. Link it.
- Admit when you're arguing against a position you respect. Steelman once,
  then cut.
- Use real numbers. "47× slowdown," not "significantly slower." "2019,"
  not "a few years ago."
- Length that matches the idea. Dijkstra on `goto` is three pages. Yegge's
  *Kingdom* is twenty. Both correct. Both sized to the claim.

**Don't:**

- "In today's fast-paced world of software…"
- "Let's dive in" / "Let's explore" / "Let's take a look at"
- "On the one hand… on the other hand…" as a structural crutch.
- End with "What do you think? Let me know in the comments!"
- Pad with three-item lists where the third item is filler.
- Explain things the reader obviously knows. Motivated developers stopped
  reading when you defined `malloc`.
- Open with a dictionary definition of anything. Ever.

## The anti-AI purge list

Grep these out before shipping. Each one is a tell.

- `delve`, `dive into`, `unpack`, `walk through`, `explore`
- `leverage`, `robust`, `seamless`, `comprehensive`, `cutting-edge`,
  `powerful`, `innovative`, `scalable solution`
- `in conclusion`, `to summarize`, `in this blog post`
- `it's worth noting that`, `it's important to remember`
- `in the ever-evolving landscape of`
- `the intersection of X and Y`
- `game-changer`, `revolutionize`, `unlock`
- Parallel sentence padding: *"Not just X, but Y. Not just Y, but Z."*
- Any paragraph whose first sentence previews what the paragraph is about.
- Any section that exists only because the draft "needed a section there."

## Before and after

**AI-voiced:**

> In this post, we'll explore some common pitfalls that developers
> encounter when working with distributed systems. As applications scale,
> it becomes increasingly important to understand the tradeoffs involved
> in various architectural decisions, and microservices are no exception.

**Human-voiced:**

> Every year or so I watch a team discover, painfully, that their
> "microservices" are a distributed monolith with worse latency and a
> harder deploy story. This post is about why that keeps happening and
> three questions that catch it in the design review.

The second one names the pattern, takes a side, and puts a person in the
room. That is the whole trick. It is not a secret. It is just work.

## Three skeletons

Pick one. Don't try to combine them.

**A. Name-the-thing essay** *(Spolsky, McKinley, Brooks)*

```
[Concrete situation where the thing bites. One paragraph, in scene.]
[Name it. Bold it. Define it in one sentence.]
[Three examples of it in the wild. Specific projects, versions, links.]
[Why it exists. Root cause, not symptom.]
[What to do about it. Honest — often "nothing, just see it coming."]
[Close on the name, reframed. The sentence readers will steal.]
```

**B. Extended-metaphor essay** *(Yegge, Nystrom, Gabriel)*

```
[Open in the metaphor's world. Programming not mentioned yet.]
[Establish the metaphor's rules. Have fun with it.]
[Map to the programming situation. The reader should feel the click.]
[Push past cute. The metaphor has to earn its length by doing actual
 explanatory work. If it stops paying, the essay ends.]
[Step out of the metaphor for one clean line. Exit.]
```

**C. Contrarian take** *(Graham, Norvig, patio11)*

```
[State the consensus. Fairly. In one paragraph.]
[State your counter-claim. One sentence. Unhedged.]
[Evidence: personal experience, historical pattern, or actual data.
 Pick one and go deep. Don't try all three.]
[Concede what the consensus gets right. This is where trust is earned.]
[Sharpen the claim past where you started and close.]
```

## Length discipline

| Essay type          | Sweet spot      | Failure mode              |
|---------------------|-----------------|---------------------------|
| Name-the-thing      | 800–1,500 words | Overexplaining the name   |
| Extended metaphor   | 2,000–4,000     | Metaphor breaks, you pad  |
| Contrarian take     | 1,200–2,500     | Relitigating the obvious  |
| Technical explainer | 3,000–6,000     | No thesis, just a survey  |

If your draft is longer than the sweet spot, the idea isn't bigger — the
prose is looser. Cut 20%. The essay will be better. It always is.

## Reference cuts

When stuck, open one of these and steal the move:

- **Joel Spolsky, *The Law of Leaky Abstractions*** — how to name a
  phenomenon in 1,200 words and have it still quoted 20 years later.
- **Steve Yegge, *Execution in the Kingdom of Nouns*** — sustained
  metaphor, comic timing, mean in the way that lands.
- **Paul Graham, *Beating the Averages*** — essayistic voice, the
  Blub Paradox, how to pull in an outside-field reference.
- **Bob Nystrom, *What Color Is Your Function?*** — one idea, sustained,
  never lets go. A masterclass in not diluting a claim.
- **Martin Kleppmann, *Turning the Database Inside-Out*** — deep
  technical content in clean prose, with taste.
- **Patrick McKenzie, *Don't Call Yourself a Programmer*** — direct,
  specific career advice without motivational-poster energy.
- **James Mickens, *The Night Watch*** — humor as load-bearing structure.
- **Edsger Dijkstra, *Go To Considered Harmful*** — short and mean. The
  proof that an essay can fit on two pages.
- **Fred Brooks, *No Silver Bullet*** — how to distinguish concepts
  (essential vs. accidental) in a way readers keep using.
- **Richard Gabriel, *The Rise of Worse is Better*** — the three-word
  title that became a whole worldview.

## Final check

Read it aloud. Two tests:

1. **The Slack test.** Is there a sentence you'd paste into a group chat
   to end an argument? If not, the essay doesn't have its line yet.
2. **The 2040 test.** Strip out every library, language, and product
   name. Does the essay still have a point? If yes, ship. If no, the
   point was the stack, not the idea — and the essay will rot with it.

If both pass, you're done. Post it.