Eighth episode of the AI & Docs podcast series is up! In this one, Tom and I talk about what makes documentation genuinely beautiful versus merely functional, how Calvino’s literary principles apply to docs, why our role is shifting from creating to judging AI-generated content, the psychological toll of endless review work, and why most hastily-built tools lack the craft to last.
You can watch / listen to the episode here:
Some of the things I said:
On lightness in documentation #
Docs that are light are like docs that are not burdening the reader. When you’re writing a document and you are in full control of the knowledge — you know it very well, to the point that you can explain it to anybody, even kids — that’s lightness to me. It’s like you’ve already moved everything that makes knowledge heavy and you’re able to carry that with almost no weight to the reader.
On docs brutalism #
Docs brutalism to me is docs without a soul, without like some at least some angles of fun that you might have had creating them. We have a ticket, we have to document the feature, we have to write the release notes, it’s a chore. We do it and we create these brutalist blocks where everything is the same and it’s everything is flat. It’s concrete.
On taste and discernment as human value #
Beauty is part of it, but I think it’s part of a wider thing which is perhaps taste or discernment or something that only a human can have. What the human brain can bring is an opinionated view of what you can do with all these pieces. I would never trust a recipe generated by an LLM. But by a human, yes.
On why AI still needs human direction #
You still need a map. You still need something that goes beyond what the LLM can fetch and can assemble for you. You need ideas, you need inspiration to point a machine to build something. Getting that just from the LLM is — you’re not gonna get anything powerful or original from it.
On accepting 70% and avoiding the review trap #
Accepting seventy percent from AI is very hard to accept, but it’s very liberating as well. When you accept that most of the output will be good anyway, you put some deterministic checks in place, you review things as you would review things coming from a human being — and that’s when you can focus on higher level stuff. In my case, perhaps I’m a bit too trustful of AI, but it also avoided getting into this reverse-curator trap.
On craft, care, and intent #
The three things that matter — not just in creating tools, also in writing — are craft, care, and intent. Craft means that you know your craft, you know when things are well done. Care means that you care about the thing. Again, this is not something a machine can do because it has no motivation to do it. And intent connects to motivation. It’s a mix of motivation and emotions — all ingredients that only a human can bring to the mix.
On vibe-coded tools and accumulated taste #
The problem is when a tool is built for an audience of one and promoted as something greater. We tech writers might now feel empowered to build tools, but we are entering a space where developers have been building tools slowly for decades and have accumulated lots of taste and experience. We cannot just pretend to replace that with something vibe-coded in five minutes.
On ownership and strategy #
The most miserable scenario for a tech writer is not having a strategy and not owning anything. Because you are at the whims of everything in the org. What matters is ownership — like you own part of the content generation — and being strategic about how you produce content. You have the pipelines, you have the procedures, you’re not just trailing behind developers.
On where the profession is forking #
The profession is going to go into two directions. One is more like a devrel — a writer who builds upon a foundation of content, uses AI to generate more, but also creates foundational content and overarching explanations of how to assemble things. The other role is like the pipeline engineer, the writer who is tending to automated or AI-driven content production.
On local models and the future of inference #
What I think is that local models will certainly cover a more significant share of our AI time. Why? Because cost. If inference cost doesn’t go down, we’re gonna need something we can run on our laptop using solar power or something similar. And it’s cheaper, it’s more sustainable, greater privacy too. On a MacBook Air with 60 gigabytes of RAM — under a thousand dollars — you can run an 8-billion-parameter model at decent speed already. Which was quite unthinkable years ago.