Blog / Build with AI /
Writing documentation people actually read
Nobody wakes up wanting to read documentation. They arrive at it stuck, a bit annoyed, and with one question: “How do I do this thing?”
If your docs don’t answer that question in the first few seconds, they leave. Then they email you, or leave a bad review, or just stop using your tool.
I’ve written about writing docs for a tool that people actually read from the tool-builder’s side. This post is the practical version: a method you can follow for any small product, site or plugin, and how to use AI as a drafting partner without ending up with filler.
Why documentation goes unread
Most docs fail for one of four reasons:
- They’re organised by the builder’s structure, not by the reader’s goals. “The Settings Panel” is a feature. “Change the colour of my buttons” is a goal.
- They explain everything, so the one answer is buried under twelve things the reader didn’t ask.
- They assume knowledge the reader doesn’t have.
- They’re out of date, so after one wrong screenshot the reader stops trusting any of it.
The fix to all four is the same: write from the reader’s question backwards.
Step 1: collect the real questions
Don’t start from your feature list. Start from what people ask. Sources:
- Support emails and messages
- Reviews and comments
- Questions you answer more than twice
- Search queries on your own site, if you have search
- The first things a new user would try
If you have no users yet, imagine a new user on their first day and write down the first ten things they would try to do. Then ask a friend who hasn’t seen the tool to try it and tell you where they got stuck.
A page title should sound like the question: “How do I export my list?” beats “Export functionality”.
Step 2: give every page one job
A help page should answer one question. Split anything that tries to do two things.
A reliable structure:
- A title that is the question or task.
- One sentence of what you’ll achieve, such as “This takes about two minutes.”
- Numbered steps, each one action.
- What you should see at the end.
- If it didn’t work: the two or three most likely causes.
Short, repeated structure is a gift. Readers learn it once and scan the rest.
Step 3: write the steps properly
The step list is where most docs earn or lose trust. Some rules:
- One action per step. “Click Settings, choose Export and select CSV” is three steps.
- Use the exact words on screen. If the button says “Save changes”, don’t call it “Submit”.
- Put the action first. “Click Export” not “The Export button can be clicked”.
- Say where. “In the top menu” removes the hunting.
- Avoid “simply” and “just”. If it were simple, they wouldn’t be reading.
- Tell them the result: “A file called list.csv appears in your downloads.”
Read your steps aloud as if you were guiding someone over the phone. If you stumble, the step is unclear.
Step 4: use screenshots carefully
A good screenshot saves a hundred words. A bad one causes harm.
- Crop to the relevant part, with a highlight on the thing to click.
- Add alt text, for accessibility and for people with images switched off.
- Keep them few. Every screenshot is something you must update when the interface changes.
- Never show real personal data or API keys.
For tools that change often, consider a short text description in place of a screenshot. Text ages better.
Step 5: add the four pages almost every tool needs
Start small. These cover most questions:
- Getting started: the first five minutes, from install to first result.
- The main task, done step by step. Most tools have one headline job.
- Troubleshooting: a list of “If you see X, try Y”.
- FAQ: short answers to the real repeated questions, including privacy, cost and what data is stored.
You can add more when real questions justify them. A small, correct set beats a large, stale one.
Using AI to draft docs
AI is excellent at turning rough notes into clean steps, and poor at knowing what your product really does. Give it the facts, then check what it writes.
A prompt that works:
I’m writing a help page for this task: exporting a list from my tool. Here are my rough notes of the steps: [notes]. Write numbered steps, one action each, using these exact button names: [names]. Add a line saying what the user should see at the end, and three likely problems with fixes. Don’t add any features I haven’t mentioned.
That last sentence matters. Without it, the model may invent a menu option that doesn’t exist, and your docs will describe a product you didn’t build.
Then:
- Follow the steps yourself, from a clean state, using only the page.
- Delete padding. AI loves openings such as “In this guide, we will explore…”. Cut them.
- Check tone. Plain and friendly beats formal.
- Ask for a second pass aimed at a different reader: “Rewrite for someone who has never used a browser extension.”
You can also run it the other way: paste your draft and ask, “What questions would a new user still have after reading this?” The answers point at gaps.
Step 6: make it findable
Excellent docs that nobody can find are the same as no docs.
- Link to help from inside the tool, next to the confusing bits.
- Give every page a clear title and URL. If it’s on the web, search engines can send people straight to it.
- Use the words your users use, not internal names. If everyone says “tabs groups” and you say “collections”, include both.
- Add a search box or a short index once you pass a dozen pages.
- Link related pages, such as “Next: Change the colours”.
For anyone who runs a website, this will sound familiar. Documentation is content, and the usual rules about intent and titles apply. People often type their problem into a search engine before they ever open your help centre.
Step 7: keep it alive
Docs go stale quietly. A few habits help:
- Update docs in the same session as the change. Add “docs” to your release checklist next to your changelog.
- Put a “last updated” date on the page.
- Watch for repeat questions. Every question you answer twice is a missing or unclear page.
- Give readers a way to flag problems, like a “Was this helpful?” link or an email address.
- Review twice a year, following the steps as a new user would.
Key takeaways
- Write from the reader’s question, not your feature list.
- One job per page, with numbered single-action steps.
- Use the exact words on screen and say what success looks like.
- Let AI draft from your notes, and tell it not to invent features.
- Test every page by following it cold, and update docs when you change the product.
Related reading
Pick the one question you answer most often, write the page this week, and link to it from the next reply you send. Which question is it?