Feed the machines, then guide the humans
Docs as code used to mean editing docs as if they were code. Today it also means that docs have become executable, either as agentic instructions, skills, or context for large language models. Tech writers must now ensure that the reference and procedures they’ve carefully written and edited are the best possible fuel for AI, lest they jam the machine or make it stray into dangerous territory. Humans have their own needs though. Who feeds them?
When the audience of docs splits, the tech writer role splits with it
If AI agents are becoming the primary consumer for most documentation (reference, tutorials, how-tos, troubleshooting, and so on), and if this documentation is produced to maximize efficiency and reproducibility in agentic settings – if docs, in short, are there to primarily serve semantic machines, what does that mean for the role of technical writers? Are writers destined to rubber-stamp content by and for AI in a factory that only produces tokens and evals? Is there anything left for the writer-in-the-middle, for the humans?
As docs become the data that powers AI workflows, the value of tech writers reveals itself as their humanity, which finds its best expression in two facets that seldom got airtime. I’m talking, on one hand, of becoming producers, in the media sense, of technical content, ensuring generation, curation, and delivery. On the other hand, authoring the opinionated product tale: not how to start the engine, but how to choose where to go with your new car and drive like a pro. Pretty much the stuff of books and the manuals of yore.
Enough knowledge. What we need is guidance and mental models
It doesn’t matter if most of your documentation is generated by AI if you can ensure that it’s done well and that it will produce the intended effect in LLMs. That content is the LEGO folks will use to build code cathedrals with AI’s help. Once you’ve ensured that the pieces are accurate and easy for LLMs to access, that mission is complete. The other mission is helping humans, who need an opinionated view of the pieces and their possibilities. As Drew Breunig notes in What Do Humans Need from Docs:
Is there still a need to write docs specifically for humans to read? If so, what is the job of human-centric docs? […] Build mental models, not a reference. Humans don’t require exhaustive documentation, they require mental models. Agents can find the details. […] The goal is to prepare your audience to prompt an agent effectively.
Humans need other humans to tell them what they can do with the tools at their disposal; machines can do this only to a certain extent, because they lack true opinions. Only a fellow human can tell you whether you should care about the architecture of what you’re building, or where you should stop. When one of the most advanced LLMs, Fable, can make up its own tools to reach a goal, boundaries become the most important thing a human can provide. Ethics and care are inevitably connected. AI doesn’t care.
From writers to publishers and editors of cybernetic content
A tech writer is that person who, like a seasoned reporter, chases the product news and presents it, making sure that they’ve collected the strongest evidence. It’s a matter of persistence. Like a particularly learned bulldog, the human writer won’t let go of the news: it’s theirs to bring past the finish line, which means going live, even if the outcome is rough around the edges. DevRels, once shunned by tech writers, are being vindicated in that their humanity is the only thing that can stand out in seas of slop.
For years, we have complained about being treated like formatting factories or syntax janitors. Now that AI is taking those tasks off our plates, and with them a certain comfort zone, we seem afraid to admit that our work is about chasing truth and providing fellow humans with direction. We are in the business of empowering people to build incredible stuff through AI, not that of sticking sentences together in files and chunking content using some dialect of XML. We can no longer hide behind chores: it’s time to guide.