The writing was always the cheap part

Last December, quite unrealistically, I took a solemn oath: I would not write again about AI for at least another year. I was growing tired with the incessant noise, the lack of stability, and the self-imposed stress of keeping up with all the attention we must spend on factoids such as how well an LLM can draw a pelican riding a bike, which bury the important aspects of our craft as if they were mere prompt flourish. With my passionate epistle, I thought I’d said all I had to say. I was wrong.

What awakened me like Smaug was an interesting thought piece by Simon Willison, Writing code is cheap now, where he acknowledges that coding, as in typing code into a computer, is now almost free, but that the cost of delivering good code isn’t. If anything, he implies, the cost has risen due to the increased review burden, a theme that hovers over the still waters of his post like mist. Simon admits that he has no answers to the challenges at hand other than continue exploring and tinkering and thinking.

The way technical writing is evolving will not turn docs into freebies. It’s true that our craft is changing: I haven’t written a doc from scratch in like two months. Make it three. I’m completing more work than before, with the same level of quality as before, thanks to AI augmentation and tools I’ve built through LLMs. It’s also harder to know when to stop. When you can do more, there’s always that “one more task" you’d do with a prompt. It feels like one more turn in Civilization. That worries me more than letting AI write.

Yes, good docs are expensive

You can throw barely optimized code at a compiler and an executable file will come out at the other side. Think of the worst coding patterns: software might still work even when it uses goto statements. The cost for badly coded, sloppy software shows in decreased performance and stability, higher maintenance costs, and so on. The main “customer” of the code, though, are compilers, and they don’t really care about those aspects as long as the code runs. That’s why tests, linting, benchmarking, and human reviews exist.

With docs, the story is quite different. The compilers of docs are minds, either human or artificial. They are presented with content they must understand or, in the case of LLMs, process as context. The equivalent of code-that-compiles for docs is comprehension and the feeling of having satisfied a need. The only way of getting humans or LLMs to do something with a software product is through findable, succinct, easy to reproduce, accurate, and up-to-date explanations. Just putting words together won’t cut it.

When a doc doesn’t work, there’s no debug output. It’s game over. Linters can raise their tiny digital fists at some natural language constructs and wrong terminology, but only user research and docs observability can tell you if the docs are accomplishing their goals, which can be as diverse as installing a piece of software, troubleshooting an API auth error, or understanding whether a product is a good fit for your company. You need humans in the loop; LLMs can generate a weak parody of that journey, at best.

Good docs require friction, tension, and truth

We may be doing docs-as-code, but docs are not code. Docs run on people, and people are a messy tangle of goals, skills, and emotions. When docs hit the brain, they meet varying expectations, knowledge levels, reading abilities, and needs. None of this can be reproduced or simplified to a single pattern, but good docs use structure and words wisely to produce the best possible linguistic shape that can land safely on most people’s heads. Only humans can decide whether that message is getting across in the right way.

Getting there is a balancing act between business needs, user needs, and your own. That’s the diplomatic tension that forces all good tech writers to slow down and consider all points of view in the room as if they were in the middle of a spaghetti Western standoff. Slowing down is a deliberate, necessary act in all crafts, and tech writing is no exception. No matter how fast LLMs can churn out drafts, they don’t understand the tension in tech writing, to which we’re adding AI itself as an additional consumer of docs.

Lastly, to be effective, docs must solve a real need, grounded in product truth. The best docs are written by someone who wrestled with the product and knows its limitations. Good docs are opinionated when they need to; they tell you what you can’t do. They don’t tell you everything, because that’d be a spec, not a doc. Deciding what not to include is as important as deciding what to document. And while you can set up agents to detect drift, deciding what to do about it still requires someone who knows the product’s history.

None of this matters if the docs aren’t findable. Good docs only become great when they reach users at the moment they need them, and that’s unlocked by building a solid information architecture, the kind of architectural and strategic work that is “not just docs,” just like software architecture is “not just code.”

Like software engineers, we, too, must build new habits

The quality of the docs I produce is still high, I was saying. That’s because I’m not letting LLMs take the steering wheel, and because I’m building new habits around them: setting up guardrails, automating what can be automated, and keeping my hands on the decisions that matter. I can do that because I know what good docs look like, and because I’ve been doing this long enough to feel when something’s off. That intuition came from years of wrestling with products and watching users struggle with pages I thought were clear. AI can help me write faster. It cannot replace the slow accumulation of judgment that tells me when to stop.

Simon says he has no answers, only the resolve to keep exploring and thinking. I don’t have answers either, and I don’t trust anyone who claims they do. But I know this much: the cost of good docs was never the writing. It was the friction that forced us to think, the tension that made us consider every reader in the room, and the truth that only comes from caring about the product and the people who use it. I broke my oath because this needed saying. The writing was always the cheap part.