Understand Your Audience

​

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 be:

• Technical decision maker evaluating your product → wants to understand higher level details e.g. architecture overviews
• End user relying on your product → may not be technical, looking to get started or how to do a specific task
• Developer responsible for integrating your product → needs clear and concise instructions to get to their goals

Ahead of writing any page, ask yourself: what is my reader trying to accomplish (see Content Types) and what is their prior knowledge?

​

User research is key

You can align with your tech lead or product manager to clarify the target audience, but the best insights come from directly talking to users. There is often a disconnect between what the product team thinks the product is, and the user’s actual mental model of how it works.

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 that you often end up writing documentation for yourself, and not your users. Talking to users directly helps ground your writing from their perspective.

​

Tips and tricks for understanding your audience

1. 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?
2. Incorporate feedback mechanisms. Whether it’s a thumbs up/down or a plain text field, give users the opportunity to give feedback in real time as they read your docs.
3. Use analytics to guide you. Incorporate analytics into your documentation, whether it’s page views, search queries, or drop-off & bounce rates. Knowing where users are engaging with your documentation can be a jumping off point for further research.

Remember, 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 (e.g. socials, 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