update understand-your-audience.mdx and docs.json

docs.json

@@ -30,7 +30,7 @@
       {
         "group": "Structure",
         "pages": [
-          "know-your-audience",
+          "understand-your-audience",
           "content-types",
           "navigation"
 

understand-your-audience.mdx

@@ -0,0 +1,107 @@
+---
+title: 'Understand Your Audience'
+description: 'Keep user goals at the center of your writing'
+---
+
+<Tip>
+  This article covers how to identify your audience, conduct user research, and write with their needs in mind, ensuring your documentation is helpful and effective.
+</Tip>
+
+## 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
+
+### What is a User Persona?
+A user persona is a semi-fictional representation of your ideal reader. It helps you stay focused on their needs.
+
+For example, if your audience is a developer, this persona might be Anya:
+- Name: Anya 
+- Developer skill: Intermediate
+- Languages: JavaScript, Node.js, some experience with Python
+- Developer environment: MacOS, VS Code
+- Role: Front-End Developer
+
+When preparing to write content tailored to different user persona,
+ask yourself:
+
+- What is my reader trying to accomplish?
+- What is their prior knowledge?
+
+To gain an even deeper understanding of your users' goals beyond just creating personas,
+you can add user stories and user journey maps. 
+
+User stories detail specific tasks users want to accomplish and user journey maps visually represent the steps users take when interacting with your product. These help ensure that all aspects of the product align well with the needs identified through personas.
+
+
+
+## Conducting User Research
+
+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?
+- What frustrates them most when trying to use the product or 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. 
+
+
+Here's how to gather that key user insight:
+
+**1\. Review Existing Data:** Before conducting user research, gather and review existing materials you already have about your product or your users. These could include old emails, design documents, chat conversations, code comments, and commit messages. Reviewing these data will help you build a clearer picture of how your software works and what you intend your users to do with it. Also, look through support tickets to get information on where people get stuck.
+
+**2\. Interviews:** Prepare open-ended questions to learn about their experiences:
+
+* Tell me about your experience using similar tools... 
+* What are you hoping to achieve with this product?  
+* Walk me through the steps you take when trying to perform a specific task.
+
+*Finding Users to Interview-Where to Look*
+
+Conducting user interviews is a powerful way to understand your audience, but finding the right participants can be challenging. Here are some strategies for locating potential interviewees:
+
+* **Engage with Existing Customer Channels:** Your support team, customer success managers, and sales teams interact with users daily. Tap into their knowledge and ask them to recommend users who might be willing to participate in an interview. These teams often have lists of satisfied customers or users who have provided valuable feedback in the past.  
+* **Mine Your Online Communities:** Online forums, social media groups, and community forums related to your product are excellent places to find potential interview subjects. Look for active users who regularly ask questions, provide answers, or share their experiences.  
+* **Leverage Beta Programs:** If you have a beta program for new features or releases, beta testers are often eager to provide feedback. They're already invested in the product and willing to share their thoughts.  
+* **Reach Out to Early Adopters:** Early adopters are often enthusiastic about trying new products and services. Reach out to users who signed up early or participated in initial marketing campaigns.  
+* **Attend Industry Events and Conferences:** Industry events and conferences provide opportunities to connect with users in person. Attend events relevant to your product and strike up conversations with attendees.  
+* **Offer Incentives (Judiciously):** While it's important to avoid biasing responses, offering a small incentive (e.g., a gift card, a discount on the product) can increase participation rates, especially for users who are busy or reluctant to spend their time interviewing. Make sure any incentive is transparent and doesn't influence their answers.  
+* **Use Your Network:** Ask colleagues, friends, and family if they know anyone who uses your product or a similar product. Even indirect connections can lead to valuable interview participants.
+
+**3\. Surveys** Create short, targeted surveys to gather quick insights from a larger audience:
+
+* Ask one thing per question.  
+* Use closed questions (with limited answers) for easy analysis.  
+* Keep them optional and neutral.
+
+
+
+
+## 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. *Don't just collect it \- act on it\!* Review feedback regularly and prioritize updates based on user concerns.
+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. 
+4. **Experience the Friction:** Try using your product as a new user would. Document each step and record any frustrations or points of confusion. This "friction log" helps you identify areas for improvement in both the documentation and the product itself.
+
+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**
+
+Understanding your audience and improving your documentation is an *ongoing process*. Regularly revisit your user personas, conduct new research, and update your content to reflect evolving user needs and product changes.