Writing documentation for AI

How to write for AI tools — including built-in AI assistants like GitBook Assistant

Writing content that’s great for humans and AI tools

The way that people consume documentation is changing fast. Modern docs need to be more than just a static site that humans manually browse — they also need to be formatted to be easily read by AI.

Why? Because more and more, your users are going to an AI tool like ChatGPT, Claude and Perplexity when they need information. And if you’re docs don’t show up in the answer, they may get incorrect or outdated information — which isn’t a great user experience.

Plus, many modern docs tools offer a built-in ‘Assistant’ that’s trained on your docs content and can chat to users about your product. For example, GitBook offers an Assistant that you can also embed into your website or product — so your users can always get accurate answers from information in your docs.

So what do you need to do to write for AI?

The short answer is that you don’t need to make a ton of changes to what you’re already doing. And the good news is, these guidelines will generally make your docs easier for people to read as well.

Here are some quick tips:

Use clear, hierarchical structure

Break up your content with good headings (H1, H2, H3) and don’t just write giant walls of text. Bullet points, numbered lists and shorter paragraphs make everything easier to read.

Write concise, jargon-free content

Keep it simple and skip complex technical terms unless you really need them. LLMs do much better when you say what you mean without adding fluff.

Include practical examples

Show, don’t just tell. Code snippets, API examples, and real scenarios help LLMs — and your users — understand how things actually work in practice.

Keep content current and accurate

Nobody likes outdated docs. Regular updates mean LLMs won’t give people wrong information about your latest features and updates.

Test with AI tools

Actually try asking ChatGPT or Claude questions about your docs to see how well they understand your content. You might be surprised by what works and what doesn’t.