.. include:: /Includes.rst.txt Authentic Communication ======================= We use a communication framework of Authentic Communication, employing empathy, clarity, and trust to create relevant content that is compelling to consume and technically accurate. .. _1-empathy: Empathy ~~~~~~~ It is essential to understand the needs of your target audience to create content that is meaningful and relevant to them. In your content, show your audience—developers, marketers, whomever—that you understand the challenges they face in their day. You can then write more credibly about the features and benefits of a given solution, showing them that it can resolve a common issue, reduce friction, or improve their work. .. _2-active-listening: Active listening ^^^^^^^^^^^^^^^^ Ask questions, listen, and seek to understand. Conduct interviews or surveys, or be present where your audience likes to be, such as Slack channels, GitHub, and Twitter. Ask, listen, ask again … Never be ashamed to ask a question. Don’t be embarrassed if you don’t know a term or technology. Ask! Most subject-matter experts love talking about their area of expertise. .. _3-language-choice: Language choice ^^^^^^^^^^^^^^^ Choose language—words, phrases, idioms—that takes your audience’s perspective, experience, and vocabulary into account. In content aimed at a developer audience, for example, talk to developers as another developer would. In your research, look up relevant questions or concerns a developer might express concerning your topic. .. _4-empathetic-writing-an-example: Empathetic writing: an example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You run a survey and a common developer answer is something like: *“My job is to develop solutions, but I spend only 10 percent of my time actually doing that, and 90 percent doing maintenance.”* You might write: *“As a developer, you probably get frustrated because you want to spend your workday developing new features, but instead, you find yourself bogged down with system maintenance. The solutions outlined in this article help minimize maintenance issues, letting you get back to your job: developing new solutions.”* .. _5-clarity: Clarity ~~~~~~~ Technology can be complicated and abstract, but we can help make things clearer. **Clarity of words** is critical for an audience to understand the value of a product or service. Issues that we need to address in this context include things like: - Different vendors and communities often use different names and terms for the same concepts. - Developers and business people have whole worlds of jargon they use that are obscure to the uninitiated. **Clarity of structure** and visual presentation can help make complex information easier to understand. To achieve clarity, be mindful of the following: - Technical accuracy - Leverage the knowledge of subject-matter experts. - Check terminology. - Test code samples. - Tight writing: Crisp, sharp, focused. - Compelling and accurate language. - Use examples to illustrate, where necessary. - Logical rigor and clear narrative structures - “This follows that.” - Plan ahead: your post needs a beginning, middle, and end - Start with what’s important: the goal, outcome, or summary of what we are about to read - Finish with a similar summary. - Scannable formatting: - Descriptive headers, and titles are better than clever ones. - Break up walls of text with visual aids like bulleted lists and callout quotes. .. _6-trust: Trust ~~~~~ When you focus on empathy and clarity—especially in the form of technical accuracy and logical rigor—you will establish trust with your audience. Trust plays a vital role in values-based decision-making. People make many of their decisions—including which tools and services they purchase and whom they purchase them from— based on values not solely on logic or economics. Two key ways you can establish trust with your audience when you’re writing: - **Make mindful claims.** Avoid binary claims (like good/bad) or absolute claims (best/worst). Respect the nuance and situations where your product may not be the best. - **Back up your claims with evidence**—quantitative or qualitative. Data, statistics, quotes, or testimonials from appropriate experts (users, developers, customers, etc.) all help.