The skill: Creating documentation that users actually read and that reduces support load. The difference between docs that gather dust and docs that make users self-sufficient. Good docs are a product, not an afterthought.
Structure around tasks, not features
Users don't search for "Workspace Settings API." They search for "how to add a team member." Title and structure every page around what the user is trying to do, not how your codebase is organized.
Show the happy path first. Walk through the most common use case start to finish before covering edge cases, errors, or advanced options. Most users need the simple version. The edge cases can live further down the page for the 10% who need them.
Know the four types of docs
Most products only write reference docs and wonder why nobody reads them. The Divio framework identifies four types, each serving a different purpose:
- Tutorials — learning-oriented. "Build your first integration in 10 minutes." Hand-holding, step-by-step, designed for beginners.
- How-to guides — task-oriented. "How to add a team member." Assumes some familiarity, answers a specific question.
- Reference — information-oriented. API specs, config options, parameter tables. Complete and accurate, not narrative.
- Explanation — understanding-oriented. "How our permission system works." Background, context, architectural decisions.
If you only have reference docs, you're forcing every user to reverse-engineer the tutorial themselves. Most won't bother — they'll open a support ticket.
Write for scanners
Users scan for their answer. They don't read top to bottom. If the answer is buried in paragraph 4, they'll leave and open a support ticket instead.
Headers, bullets, bold key terms. Code examples must be copy-pasteable and runnable — pseudocode, abbreviated examples, and "..." placeholders force users to guess. Real, complete, working examples save support tickets.
Search is your most important feature
Nobody reads documentation cover to cover. Users arrive with a specific question, and if they can't find the answer in seconds, they leave. Your documentation's search is more important than its structure, its prose, or its visual design.
A basic keyword search is table stakes, but it breaks on natural-language queries. A user searching "why is my webhook failing" won't match a page titled "Webhook error codes." Invest in semantic search, fuzzy matching, or AI-powered search that understands intent, not just keywords. Algolia, Typesense, or similar tools handle this well and take hours to set up, not weeks.
The gold standard now is a conversational AI assistant embedded in your docs. Users can ask "how do I authenticate with OAuth2 if I'm using a service account?" and get a synthesized answer with links to the relevant pages. Stripe, Supabase, and Vercel all have this. If your docs platform (Mintlify, GitBook, ReadMe) offers it, turn it on. If you're self-hosting, consider adding a retrieval-augmented generation (RAG) layer over your content. The cost is marginal, the support ticket reduction is not.
Make your docs LLM-readable
Here's the reality: a growing share of your users will never visit your docs site. They'll ask Claude, ChatGPT, or Copilot how your product works, and the LLM will either answer correctly (because it could access your docs) or hallucinate something wrong (because it couldn't). If LLMs can't read your docs, your documentation is failing silently for an audience you can't even see.
Add an llms.txt file. This is the emerging standard, think robots.txt but for LLMs. Place it at your docs root (docs.yourproduct.com/llms.txt). It's a markdown file that acts as an index: your product name, a one-line description, and categorized links to your key doc pages. Alongside it, serve an llms-full.txt that concatenates all your docs into a single markdown file LLMs can ingest in one pass. Anthropic, Cloudflare, Mintlify, and Cursor already do this.
Serve clean markdown versions of your pages. Many AI crawlers don't execute JavaScript. If your docs are a single-page app that renders client-side, they're invisible to LLMs. Server-side render everything. Better yet, offer .md versions of each page alongside the HTML.
Don't block AI crawlers. Check your robots.txt. If you're blocking GPTBot, ClaudeBot, or other AI user agents, you're ensuring that LLMs give wrong answers about your product. That's worse than no docs at all, because users will trust the wrong answer and blame your product, not the LLM.
The test: ask an LLM "how do I [common task] with [your product]?" If the answer is wrong or vague, your docs have an LLM accessibility problem.
Keep docs alive
Stale docs are worse than no docs — they actively mislead users and erode trust. Include doc updates in your release checklist. Every feature that ships without updated docs is a support ticket waiting to happen.
The test: can a new user complete the task following only these instructions? If not, the docs are incomplete. Run this test with an actual new user, not a teammate who already knows how the feature works.
Do's and Don'ts
Written with ❤️ by a human (still)