Christian Arango
Blogs

Resources

From writing docs to directing the agents that write them

Christian Arango4 min read

AI already drafts documentation from the code. How I see the technical writer’s role changing, why it matters, and five ways to get ready.

Near the end of a technical interview I ran recently, the candidate told me she had almost left out her AI work. She was afraid many technical writers still resist it, so she had planned to show only the “classic” side of the job. That moment is why I’m writing this: the classic side is exactly the part that’s going away.

The short version

In a couple of years, I believe most companies won’t hire someone just to write documentation. AI is already doing it. With access to the codebase, it drafts docs the moment a change or a release ships. The technical writer’s job moves to two things: reviewing what the AI produces and designing the reader’s actual experience. Grammar stops being the bottleneck. AI usually does a good job there.

That’s not bad news. It’s a promotion, if you take it.

From writer to director

From writer to directorBefore: product, then a technical writer who writes every page, then documentation. Now: code and releases feed an AI agent that drafts; the technical writer reviews and directs it, and the result reaches the reader. The writer turns the style guide into the agent’s instructions.BEFOREProductTechnical writerwrites every pageDocumentationNOWCode andreleasesAI agentdraftsTechnical writerreviews and directsReaderexperienceStyle guide → agent instructions
Before, the writer drafted everything. Now an agent drafts from the code, and you direct it with the style guide and review it before it reaches the reader.

The role is shifting from writing documentation to managing the agents that write it. In practice, that means your style guide stops being a PDF nobody opens. It becomes the framework you give the model: what to say, how to say it, which words to use, and which to never use.

The tools already exist. Claude skills, Gemini Gems, and instruction files like CLAUDE.md let you teach an agent your voice, your templates, and your rules once, then reuse them on every page. I built one of these for the Priority Commerce documentation: a Claude skill that loads each product’s reference package before it writes a line. The real value: the rules finally lived somewhere a machine could follow them.

What the machine still gets wrong

AI makes things easy. It also makes it easy to make a big mistake if you don’t pay attention. A confident paragraph about an endpoint that doesn’t exist reads just as well as a correct one.

That’s where we come in:

  • Accuracy. Someone has to check the output against the product, not against how plausible it sounds.
  • Context. You don’t get every nuance of a product from Jira tickets and a few dailies. Knowing what the feature is for, and who struggles with it, is still human work.
  • Consistency. It’s easier than ever to keep docs consistent, and teams still skip the check. A style guide only works if someone enforces it.
  • The reader. Navigation, examples, the order things appear in, the moment someone gives up: that’s experience design, and it’s ours.
The review layerAn AI draft passes through four human checks: accuracy, context, consistency, and the reader. Only then is it published. A draft that fails a check goes back to be fixed.AI DRAFTYOUR REVIEWAccuracyContextConsistencyThe readerPUBLISHEDFix and run again
Four human checks sit between the AI draft and the published docs. Whatever fails one goes back to be fixed.

Use AI as a peer reviewer, too. It doesn’t have to change anything. It just flags what you might fix, and you decide.

Five ways to get ready

  1. Learn to write for agents. Turn your style guide into instructions a model can follow: a skill, a Gem, an instruction file. If you can explain your standards to a new hire, you can explain them to an agent.
  2. Join the lifecycle early. Documentation doesn’t come after the product. Planning, requirements, and design are where you catch the gaps, and where an agent needs your context most.
  3. Automate the boring parts. Engineering teams are busy fixing bugs and shipping the next feature. If you can set up a pipeline that pulls the OpenAPI spec from the repository into ReadMe, Mintlify, or GitBook, and keeps endpoints tagged and ordered, you just saved them a sprint. You don’t need to be a developer. You need a few simple automations.
  4. Review like an editor, not a proofreader. Stop hunting commas. Hunt wrong facts, missing steps, and pages that answer a question nobody asked.
  5. Be proactive. Most companies don’t know what a technical writer can do. Sometimes they don’t even know what they need. Your first weeks decide how you’re seen, so propose things: research what they could implement and bring it to them before they ask.

Why adapting matters

If you’re only comfortable writing documentation and release notes, this change will hit you hard. I won’t sugarcoat that.

But if you learn to direct the tools, you become the person who levels up the documentation and the whole experience around it. Not someone who checks boxes, but someone who makes the product easier to understand, integrate, and maintain. That’s a better job than the one we’re leaving behind.

And relax: if you already know how to think about readers, structure, and clarity, you have the hard part. The tools are the easy part. Start with one: pick a page, write the instructions you’d give a new colleague, and let an agent try. Then review it like it’s yours, because it is.