Your documentation isn’t just for humans anymore. Discover why structuring knowledge for both humans and AI is the ultimate technical writing superpower.
This is the existential crossroads of modern technical writing. For decades, our “North Star” was the human reader. Now, we are suddenly writing for a dual audience: the person with the keyboard, and the LLM that mediates their experience.
Lately, there’s been a lot of healthy debate around our teams here at Google:
which audience is more important? are we just building the scaffold for our own replacement?
The gatekeeper and the truth
The short answer is that the human is still the priority. But the long answer is that AI has become the gatekeeper.
I felt this shift personally while testing a new command recently. I was using an AI-powered CLI that flagged my input as wrong. It wasn’t that my logic was flawed, but the AI was misguided based on outdated, poorly structured docs it had crawled elsewhere. It couldn’t “ground” itself in the current truth because the right information wasn’t structured for it to find, or hadn’t been updated.
That’s the risk. If a human can’t understand your docs, they won’t use your product, but if the AI can’t find them, the human might never even see them. In an era of AI-integrated IDEs and chat-based support, the LLM is often the first consumer of your work.
The human still owns the “Why”
even as AI becomes the first point of contact, the human at the keyboard remains the most important reader for two reasons:
- Accountability: When an AI command goes sideways, the AI doesn’t stay up all night fixing the production outage. You do. You need documentation to be the ultimate source of truth so you can double-check the machine when things look fishy.
- Strategy vs. syntax: AI is excellent at telling you how to call an API, but it’s remarkably poor at explaining why you should. It can give you the code, but it can’t tell you if that architecture makes sense for your specific business goals.
The architect is rising
It’s easy to feel like we’re training our replacements by providing “clean data” to AI. But there is a massive distinction between writing and Information Architecture.
The “Scribe” phase of our jobs is fading. AI is already great at routine work, like churning out “Getting Started” drafts just from code comments.
But a machine can’t navigate the “tribal knowledge” in an engineer’s head, settle a disagreement between Product and Engineering, or understand the frustration of a user stuck on a bug for three hours.
By writing for AI, we’re teaching it to work for us. Designing an information experience that allows an AI to solve a 2:00 AM outage is more than routine work; it’s high-value content engineering.
The superpower of Universal Design
Striking this balance is our superpower. Most things that make docs machine-readable are the same things that save a human from a headache.
Think of it as Universal Design. Just as a sidewalk ramp built for a wheelchair also serves a parent with a stroller or a traveler with a heavy suitcase, well-structured documentation creates a “curb cut” for every reader.
Using consistent terminology and clear headers in documentation helps the human skim, and the AI categorize. Documentation is an engine that we must design for both human readability and machine extraction.
We aren’t teaching AI to take our jobs; we are becoming context providers. The technical writer of the future will ensure the most accurate information is available to whatever entity, human or silicon, needs it to solve a problem.
Bridging this gap is the only way AI can truly learn from our work to help our users succeed.
The Technical Writer’s Superpower: How to Shape Knowledge for Both Humans and AI was originally published in Google Cloud – Community on Medium, where people are continuing the conversation by highlighting and responding to this story.
Source Credit: https://medium.com/google-cloud/the-technical-writers-superpower-how-to-shape-knowledge-for-both-humans-and-ai-1a048f9dde17?source=rss—-e52cf94d98af—4
About the Author
