Technical writing advice from astral codex ten

4 min read

The Venn diagram of tech people and readers of Astral Codex Ten probably approaches a single circle.

Alexander recently wrote writing advice for the Inkhaven residency. You should read the whole thing, and I’m not going to rewrite the entire piece, but one section immediately stood out: Against explainers.

ACT against explainers

Yes. This is the original sin of content strategy. You need a pillar piece, thus you need a broadstrokes explainer that you can hang other content off. It needs to answer SEO/LLM questions within each section, but you want the detail to reside elsewhere.

In some ways, that’s the game. But going back to the developers-can-smell-marketing point, it just doesn’t fly with technical content.

There are two ways around this.

Geek out or freak out

This is how I’ve explained getting on HN front page before. You either need to go so deep on a topic that it elicits a sense of wonder from the HN commentariat, or just straightforward ragebait them.

This is fundamentally what is in the ACT advice.

Geek out: technical content lives in the specifics

Alexander has this snark in his piece:

“Suppose someone is writing an AI explainer. Everyone knows the basics of what AI is, in the sense of “it’s when computers can do things like humans”. So what do you put in your explainer? Prompt engineering advice? The reasons some people don’t like data centers? The exact number of layers in the transformer architecture? Just start printing the weights of Kimi K2, -0.4 0.0 0.84 1.23 -0.07 and so on?”

Yes. All of those are ways to make your explainer better.

  • Why does prompt engineering work?
  • Why do data centers suck/rock?
  • What are layers in transformers?
  • wtf are weights?

All of those are better explainers than the billionth “What is AI?”

Drill baby, drill

start with your broad explainer and drill down and down into the sections. Eventually one of those single sections will be detailed enough for an explainer.

Freak out: explainer your opinion

As Jan-Erik Asplund, co-founder of Sacra, used to say:

Everybody wants to be a thought leader, but nobody wants to have no heavy-ass thoughts.

Explainers don’t have to be neutral. Again, from ACT:

The more honest version of this is something like - suppose you think AI is a scam. You want to convince your readers of this. Here the content is perfectly constrained - it’s the reasons you think that AI is a scam, presented in whatever way best conveys your case to the reader. It would be pretty hard for someone who strongly believes that AI is a scam and has thought about it a lot and has good reasons for their belief to get writer’s block on their “why AI is a scam” article. They might have trouble figuring out how to arrange their essay - what to put down first - but that’s it.

Presenting what you think is wrong (or right) with the technical world you live in is a great opportunity for content. You are just explaining your reasoning. See these from Deno about the JavaScript ecosystem:

Or these from Momentic about AI ‘slop’ and testing:

Or this from Inference about custom models:

Each contains personal insight and argument to explain their reasoning.

Other advice from ACT for technical content

  • What can’t the reader get from a prompt? If a model can regenerate your take in thirty seconds, skip it. The whole bar for publishable technical content in 2026.
  • Proximity to first-level facts. Scott’s ranking: living with the tribe > reading the primary source > reading someone who did > tweets about that person. “We actually built it” beats “we read a blog about someone who built it.”
  • Conflict and mystery beat neutral framing. Don’t open with “here are the two patterns.” Open with the puzzle: Twitter fans out on write, Instagram on read, why the split?
  • Effortposts everywhere. Most technical niches have no canonical reference. Any competent, cited, depth-first version becomes the canonical one by default.
  • Kill “obviously.” If it is, don’t say it. If it isn’t, you’re insulting the reader. Same goes for “simply” and “just.”
  • Don’t over-hedge. Stacked qualifiers read as nervous. Say the thing, then calibrate once if you need to.
  • Respect the runway. Don’t burn the first paragraph defining terms the reader knows or narrating how you came to write the post.

All the articles linked in this piece (apart from the ACT one) were written or edited by Argot. If you’re interested in working with us, shoot us an email at work@argot.dev