In this article, you’ll learn how to identify your audience, conduct user research, and write with their needs in mind.
Identify your primary audience
Writing for multiple audiences leads to compromises that satisfy no one. Each piece of content should be laser-focused on one specific user persona.
Your audience might include:
- Technical decision maker evaluating your product. They want to understand higher-level details. For example, architecture overviews.
- End user relying on your product. They may not be experienced with your product yet and they’re looking to get started or learn how to do a specific task.
- Developer responsible for integrating your product. They need clear and concise instructions to connect their product to yours.
- AI agents and large language models retrieving information to answer user questions. They need well-structured, unambiguous content with clear relationships between concepts.
Before writing, ask what are your readers trying to accomplish and how much prior knowledge do they have. See Content types for more information on aligning your content to user needs.
Conduct user research
Work with other people on your team who know your users well like UX researchers or product managers to clarify your target audience. The best insights come from talking directly to users. Often, there is a disconnect between how the people who build a product and the people who use a product think about it.
You have the curse of knowledge. You know how everything works, but that’s detrimental to your end user.
- CT Smith, Head of Docs at Payabli
Talk to users to understand:
- How do they describe your product functionality?
- Do they use any unexpected words or names to describe your product?
- What do they wish they had more knowledge of?
- What is explicitly missing from your documentation?
A common mistake is writing documentation for yourself, not your users. Talk to users to learn how your content can fit their perspective.
Write for AI agents and LLMs
Large language models and AI agents are an increasingly large share of your documentation’s audience. Developers use AI coding assistants that retrieve documentation to answer questions, generate code, and troubleshoot issues. Consider how AI tools process your documentation to help the people on the other end get the most out of your docs and your product.
The good news is that practices that make documentation LLM-friendly are the same best practices that make documentation clear and useful for humans. Well-structured, unambiguous content benefits everyone.
- Use clear, descriptive headings
- Use semantic markup correctly
- Be explicit about prerequisites
- Avoid vague references
- Use consistent terminology
- Define acronyms and jargon
- Provide complete, runnable code examples
Tips and tricks
- Get embedded in support: You’ll see the pain points that bad docs cause. Ask your support team, how do people think about the product? What are the most common problems people have that we could educate them about?
- Incorporate feedback mechanisms: Whether it’s a thumbs up/down or a plain text field, give users the opportunity to give feedback as they read your docs.
- Use analytics to guide you: Incorporate analytics into your documentation. Review page views, search queries, or drop-off and bounce rates. Knowing how users engage with your documentation can be a jumping off point for further research.
- Test your documentation with AI agents: Ask an AI assistant questions about your product. If the assistant struggles to provide accurate answers or can’t find information that exists in your docs, that’s a signal your documentation needs improvement.
There will always be edge case audiences that cannot find what they need in your documentation, but you can’t write to serve everybody.
There can be an urge to document every single thing because all information is potentially valuable to someone. But too much content becomes difficult to navigate and maintain. Use communities—like socials or Slack—to serve niche use cases, which can fill the gaps better than trying to over-document everything and spreading yourself thin.
- Ethan Palm, Senior Manager of Docs at GitHub
