| name | programming-essay |
| description | Write a programming essay or blog post in the voice of the canon —
Spolsky, Yegge, Graham, Mickens, Dijkstra, Brooks, Nystrom, Kleppmann,
patio11. Invoke when the user wants to argue an idea about software,
architecture, languages, or the craft — not a debugging war story
(use debugging-story for that), not a tutorial, not a release note.
The audience is working developers worldwide with taste and strong
opinions of their own.
|
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, exploreleverage, robust, seamless, comprehensive, cutting-edge,
powerful, innovative, scalable solutionin conclusion, to summarize, in this blog postit's worth noting that, it's important to rememberin the ever-evolving landscape ofthe intersection of X and Ygame-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:
- 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.
- 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.
