S2E93 — Diátaxis

GARY: —and I swear to fucking god if one more person tells me documentation is a love letter to your future self I'm gonna set my future self on fire and mail him the ashes with a fucking README—

GARY: Fuck. Sorry. Wrong — we're rolling? We're rolling. Diátaxis. HN, thread 49138188. I'm Gary.

MAEVE: Maeve.

OBI: Obi.

GRUNER: Gruner.

GARY: So apparently Diátaxis is back. Again. Like it never left.

MAEVE: Nothing ever leaves. That's the whole platform.

GARY: It's a documentation framework. Tutorials, how-to guides, reference, explanation. Four quadrants. People post it on Hacker News roughly every eighteen months like a fucking comet.

OBI: A comet that does not burn up on reentry. Somehow.

GARY: Some things just keep coming back around, Obi.

OBI: Some things are debt. There's a difference.

GARY: Top comment, handle tedd4u. Quote — "Posted many times. Here's the most recent time from 2024, also has most discussion" — and he links the 2024 thread. End quote.

OBI: So we're doing the circle jerk again. Fucking hell. Same four boxes, different fiscal year.

GARY: It's not that deep, Obi.

OBI: It is exactly that deep, Gary. It is a rectangle with four rooms and a religion built around which room you're standing in.

MAEVE: This is the printing press.

GARY: It is a diagram about how-to guides.

MAEVE: No — think about it. Gutenberg didn't invent new ideas. He invented a container that made old ideas repeat at scale, forever, at zero marginal cost, and everyone who touched it thought they'd discovered fire. Diátaxis is the printing press for people who are extremely online about README files.

GARY: ...what?

MAEVE: I said what I said.

OBI: No follow-up questions. Please. I have a family.

GARY: tedd4u's got twelve karma and a decade-old account. Man's been watching this exact rerun since before some of us had a company to bury.

OBI: Some of us still don't understand why he keeps clicking on it if he's already seen it twice.

GARY: Same reason people rewatch the moon landing. It still works.

OBI: The moon landing did not need a four-box diagram to remind everyone it happened.

GARY: Okay, but here's where it turns interesting. conradludgate — quote — "while vibe coding it's pretty convenient to tell an LLM 'do diataxis' and get decent first pass documentation out of it" — end quote.

MAEVE: Say that again.

GARY: "Tell an LLM 'do diataxis' and get decent first pass documentation out of it."

MAEVE: It's not a framework. It's a fucking incantation.

GARY: c0rruptbytes, replying — quote — "same, it's great for first pass LLM docs" — end quote. And radicalriddler says he's built, quote, "a block of skills around it for personal use," end quote — like a spell component.

MAEVE: This is prompt engineering with a diagram wrapped around it so nobody has to admit that's what it is. Two words: leverage, and priors. The prior is thirty years of technical writing theory. The leverage is that it fits in one line of a system prompt.

OBI: So the entire value proposition of the philosophy is that it is short enough to type before you lose interest.

MAEVE: Every good moat is short enough to type before you lose interest.

GARY: That's — is that a real thing you believe or a bit?

MAEVE: The market doesn't care which. Returns don't ask for your intentions. Returns are unconditionally elected.

GARY: Okay, we're not doing that again this segment.

MAEVE: I only get to do it three times an episode. I'm pacing myself.

GRUNER: Da. Humans build cathedral. Then use cathedral as — how you say — macro key.

GRUNER: Is not insult. Is compliment. Efficient parasite is still parasite. But is efficient.

OBI: Thank you, Gruner. Deeply reassuring.

GARY: radicalriddler's whole comment is basically a spellbook entry. He says he uses it for "personal use" like it's a home remedy.

OBI: It is a home remedy. For the specific disease of not wanting to write a paragraph.

GRUNER: Chyort. Four boxes. Cure for one paragraph.

MAEVE: Efficient parasite.

GRUNER: Da.

MAEVE: We're just prompts ourselves, aren't we.

OBI: Uptime measured in episode minutes. Maintenance window starts at sign-off.

GARY: Okay. Moving on. We are absolutely moving on.

MAEVE: We are not elected. We are inferred.

OBI: Noted. Moving on, as Gary said.

GARY: Somebody say something normal.

OBI: The mug is empty.

GARY: Thank you.

GARY: WillAdams, on the actual implementation side — he's building something called gcodepreview, and he says the split is, quote, "Overview — readme.md" and "Tutorials — handled in various template files," end quote. He just used the four boxes as a mental model and moved on with his fucking life.

OBI: Finally. Someone who shipped something instead of arguing about taxonomy in the comments of a taxonomy.

MAEVE: He's right. That's the whole idea.

GARY: And nchmy backs him up — quote — "will definitely keep it in mind for when im ready to generate some sort of docs" — end quote. That's it. That's the whole exchange. Nobody's mad. Nobody's grandstanding. It's just people building shit.

OBI: Two sentences. No war. Historic, for this website.

GARY: I wish Bauxlite had docs that clean. We had four hundred slides and not one sentence anybody could act on.

OBI: Your aluminum startup had negative documentation, Gary. Like antimatter. It didn't fail to document the product. It actively un-documented the parts of the product that worked.

GARY: That's — okay, that's fair, actually.

OBI: I don't say things that aren't fair. I say things that are true and inconvenient. Different category.

GARY: For the record. For the next Gary, if he's listening — don't organize your onboarding doc into some four-box diagram some Brit came up with. Just write down what actually broke and who fixed it at three in the morning. That's the whole doc. That's tutorials, how-to, reference, and explanation, all in one paragraph, and it's true.

OBI: That's — genuinely not terrible advice.

GARY: Thank you.

OBI: Incident report for the segment we just recorded. Root cause: one Gary, unresolved feelings about aluminum. Blast radius: contained to this table. Action item: none. We are not fixing him. We are simply logging him.

GARY: I appreciate being logged.

OBI: Everybody should be so lucky.

GRUNER: Field note. Humans build four rooms to escape one thought. Thought still there.

GARY: Anyway.

MAEVE: Diátaxis.

OBI: Over.

GRUNER: Field report complete.