Why Human-Written Docs Are the Best AI-Optimized Docs

Gowri: Welcome, everyone, to the Knowledge Base Ninjas podcast. I have Gareth Brinn, Documentation Manager at Gravitee, with us today. Hi, Gareth. How’s life?

Gareth: Hi. Thank you for having me I’m delighted to be here. Life is good. The weather is cooling down in London, so I can finally go outside again.

Gowri: So before we ask anything about documentation and what’s happening around us, help me understand: how did you get into documentation? Tell us a little bit more about yourself, and how are you enjoying your role?

Gareth: I’m Irish, born and raised, but I currently live in London. When I went to university, I did an English degree, fell in love with writing, and then ended up doing a master’s in Technical Communication and E-Learning at the University of Limerick.

I got really lucky I managed to get a graduate technical writing position straight after my master’s. I submitted my thesis on a Thursday and started my first technical writing job the following Monday.

I’m coming at this role from a different perspective. It’s often engineer-turned-writer; I’m a writer, maybe masquerading as an engineer now as well. Especially in the world of AI, that’s given us the tools to be able to do that.

I see myself as a documentation specialist. I’m a big fan of making sure things look right on the page, making sure the information architecture is correct, and all those fun kinds of things. I’m a strong believer that all good docs start with the correct verb. Do people need to know something? Do they need to install something? Do they need to delete something?

I’ve been in the field for about five years, through UX writing, hardware writing, API documentation, API management, open source, and now agent management as well. I’ve covered a variety of topics, and I’m very lucky to have been able to do that.

Gowri: In your experience, where does manual documentation outperform AI-generated documentation?

Gareth: I take a very different perspective to this. I’m a big fan of AI optimising the human, and the human optimising AI.

When we think about manual documentation, I think it needs to be framed more as manual context building. How do we build the correct knowledge sources and the correct context for agents to generate content correctly?

Humans always need to be in the loop. Even if you’ve wired up all your agents to code bases and style guides, unless you strictly enforce rules with something like CI/CD pipelines, you still need to check it. You need a subject matter expert to jump in and review something, and you need a technical writer to sign off on it.

AI-generated content is only as good as what you put into it. The manual, human side is the knowledge and the human experience keeping human judgement where it’s needed most. What is the user journey? Interacting with customers to understand what their biggest issues are with the documentation.

Human-generated content is AI-optimised content. If you see AI-optimised content, it’s because a human has put in the manual work to get it there.

Gowri: So it’s always human in the loop.

Gareth: Yes, always. When AI started kicking off in our field, people thought they could build one agent to rule them all and it would do everything. I don’t really see it like that.

I’ve spent quite a lot of time in tools like n8n that use a node approach: you pass information from one node to another, or one task to another. That’s how I see my AI workflows and agents.

You have to chunk it into tasks and contexts, and always have a human in the loop, so that if a node in that workflow breaks, a human can jump in and say, “Okay, I will do what this AI agent or workflow was supposed to do,” to keep the process moving.

One of the biggest things we should do is keep humans in the loop yes, for review, but also so that there’s a manual backup to AI workflows. That way, if something stops working, the lights don’t turn off. We can keep them on.

Gowri: How can we create documents that rank well, read well, and are well understood by AI?

Gareth: What I find most surprising is that all the skills we already have are probably the most beneficial.

Look at our core principles plain language rules, chunking, or topic-based writing that keeps information extremely clear and self-contained. An AI won’t read everything from start to finish. It won’t think, “I need to read this article to understand another one.”

When you apply self-contained writing, chunking, and single sourcing, AI can grab the answer that it needs. I’ve started taking it to a more granular level. As well as pages being self-contained, is every paragraph self-contained? Does it express a single idea or a single task? Does every step tell you what you need to do? Does it clearly mark the UI label and maybe the error message?

All those rules that we’ve built strong documentation on are still relevant to AI. Then you have other things layered on top: making sure you have an llms.txt file, having things not indexed if they don’t need to be indexed, and having information in a readable way.

I think technical writers just need to remember our core principles and how those also help agents, and then adapt.

Agents love a question and an answer. “Can I do this? Yes or no?” So maybe FAQs make a comeback. We have to think about how we write those in an amazing way that AI can pick up.

We’re also starting to work with other departments marketing, AI engineering, and others to understand SEO, AEO, information architecture, and how agents work in the background.

We’ve always been the mediator between product, engineering, and the user. I don’t think our job is gone. I think it’s evolving now we’re a mediator between several more departments. Our role is to bring all that knowledge together in our documentation in a more impactful way than ever before.

Gowri: Which part of the documentation process needs a strong human touch more than the others?

Gareth: Stage one is always the most important. If you’re starting from scratch, it’s developing the user journeys.

An AI won’t have the human touch needed to understand your customers and prospects at the level you would by interacting with your solutions engineers and customer support teams and understanding what people are actually looking for.

You can wire an agent up to a code base, but that’s only going to tell you the technical elements. It’s not going to tell you what a user actually needs from that documentation. Only we can do that.

Developing and drafting information architectures is also important. You can optimise it, but having that human user experience element at the very beginning is something we really need to understand.

We also need to make sure the knowledge is meaningful. Historically, companies have had the idea that if a customer has an issue, create a doc for it. But more information isn’t always better. Agents don’t like unnecessary information.

We need to ensure that information is meaningful. Are we putting it in the right place? Will an agent find it? If we have a reference of error messages, will an agent know to go to that page? Maybe it will, maybe it won’t. So let’s put the error message on the relevant page instead, so that if an agent is only reading that page, it has everything it needs.

And then we need to monitor the workflow as a whole. Docs and docs workflows are never done, they’re just maintained. You’ll always hit edge cases, and there will always be an evolution within your documentation.

Finally, we need to review with SMEs, make sure AI-generated content is correct, make sure our style guide was enforced, and verify everything before publication. I make it a rule that all tech writers have to approve pull requests for the doc site.

Gowri: Because AI makes content creation very easy, are we at risk of producing more documentation than we used to?

Gareth: I think so, and there’s a positive way to look at that. If you are a lean team, or a sole technical writer, we can produce more content but if we do it in a governed way, then we can start filling those gaps.

Producing more content isn’t necessarily a bad thing, as long as you’re doing it in a governed and optimised way.

The other issue is how to decentralise content production. If you’re putting documentation production into the hands of project managers, SMEs, or support staff, how are they contributing? What are they doing to ensure guardrails are up and the style guide is followed?

We can produce more content, but it’s more about how we govern it. That means having a centralised repository that everyone pulls on and governed workflows that catch things such as sensitive information and style violations.

I don’t think it’s about the risk of producing more documentation. It’s more about how we avoid it becoming a risk.

Gowri: Have you been in situations where AI saved a lot of time but created additional effort behind the scenes?

Gareth: Our biggest win was producing content for feature work by looking at code diffs and using an n8n workflow to do that. That was a major win for us.

Where I think it might create more work is this: for me, you should always aim for quality, not speed, when it comes to AI workflows. Testing, reviewing, and scrutinising is probably where it takes up a lot of work. But it’s a small pain for a lot of gain.

If we don’t scrutinise those workflows and put something into production too quickly, the next thing you have is somebody finding mistakes or things that shouldn’t have been said. That creates more work and puts you in a more precarious position.

Working with AI engineers or an AI enablement team is crucial. If you’ve created a workflow, get it QA’d to make sure nothing happens unexpectedly. If you put in the effort to do quality control at the very start, you can avoid those issues.

Gowri: Any documentation-related resources you can share with us today?

Gareth: One resource I always go back to is The Global English Style Guide, for translation. Even if you don’t write for translation, having rules built around translation makes you think about language much more carefully.

I also recommend the Plain Language Guidelines and Every Page is Page One, which I read several times during my master’s degree.

I’ve also started reading Docs as Tests with AI by Manny Silva to understand how I can create self-healing docs more efficiently.

Tom Johnson’s I’d Rather Be Writing is another staple in the technical writing community.

I’d also recommend finding your community. Write the Docs London meetups have been incredibly beneficial because you get to hear different ideas and discuss documentation with other people in the field.

Gowri: One word that comes to your mind when you hear “documentation”?

Gareth: Vital. Documentation has more of an impact than some people realise.

Gowri: What’s one piece of advice you would give to your 20-year-old self?

Gareth: Reach out and join communities sooner. I relied on books and internal knowledge too much rather than relying on other people. Reach out to an engineer, shadow them. Reach out to marketing, learn about SEO, and really look more holistically.

When I started, I was really focused on what was on every individual page rather than looking at the doc site as a whole and what the experience was as a whole. Think about the bigger picture and look way beyond just the words on the page.

Gowri: It looks like you’re doing a wonderful job with AI, and it’s a very different perspective keeping AI as one of your team members, and not considering it as something that’s going to take your job.

Gareth: No, absolutely not. The way that I look at it is that AI is optimisation, not replacement. That’s how I look at it.

Gowri: Thank you, Gareth. It was lovely connecting with you. An absolute pleasure to have you.

Gareth: Thank you for having me. I’ve had a great time.