headshot of a smiling women with short hair and glasses and a smiling man with short light hairVeronica Beck and Robert Perry, Salesforce.org
October 1, 2021

When technology is used for good, it can change the world. It can be one of the most powerful equalizers of our time, providing access to data, knowledge, and connections. Technology can also create barriers. When documentation is hard to understand, it can make intimidating technology even more frustrating. So how can we make our technical documentation accessible, approachable, and friendly? How do we ensure our documentation creates bridges rather than walls?

Jon Varese, Senior Director, Documentation, Salesforce.org, came up with an initiative for the Salesforce.org Documentation Team called Compassionate Technical Writing. We want our documentation to be more than a basic how-to that simply walks a customer through a product’s features. Instead, our vision is that the documentation be a part of the amazing connective tissue that unites our customers.

Through countless interactions with members of our community, we’ve learned that it’s not enough to write docs that simply describe how to use our products. We want to not only inform users how to use technology but also reflect an understanding of the greater purpose that technology serves. Our readers are doing amazing work in the world. We want to tell stories — their stories — and let users know that we care about them.

In this article, we herald the concept that you can create technical documentation that envelops and demonstrates compassion for the reader — which may seem like an odd or unusual pairing but actually produces content that is helpful, approachable, and accessible. We will explain our team’s definition of compassionate writing and share how you can incorporate similar ideals into your content and processes:

  • Create content that people can learn from and relate to
  • Adapt and embrace compassion in your career and writing
  • Build a rapport with your audience

Our hope is that our ideas will inspire you to identify ways that you and the members of your team can produce content with a focus on humanity and compassion.

Technical and Human are not Mutually Exclusive

Technical writing isn’t the type of writing that typically draws you in. It’s usually somewhat dry and boring, and procedural to the point of being bland and unfeeling — a utilitarian kind of writing that takes you from one task to another without much warmth and not much beyond that. But it doesn’t have to be.

As writers with a Compassionate Technical Writing approach, we’re guided by questions like:

  • How do we feel when we’re engaged in technical writing? Are we inspired? Are we passionate about our work? Do we feel connected with our readers?
  • How do we think about the people who will be reading our documents, and are we focused on what they’ll experience while reading them?
  • And perhaps most importantly, do we believe that what we write actually matters?

When the answers to these questions are affirmational, we know that we’re on the right track. When we write with compassion, with a real and human understanding of what it takes to use our products, we’re serving our readers and ourselves to the best of our abilities.

What is Compassionate Writing?

We like to think of compassionate technical writing as a cross between a how-to and a love letter to our readers. That might sound a little strange, but we’re striving to create documents that are not only clear and technically accurate but also let the reader know we’re right there with them, cheering them on as they wade through all the conceptual and technical challenges they face.

We want every reader to feel like we’ve been there too, that we get it, that we’re committed to their success, that we care about them, and that we’re on their side. We write this way, not because compassion is our latest marketing tool, but because we believe that our readers deserve the best from us. And that the best comes from a mindset of connection and compassion.

Why Compassionate Writing Matters

Why write technical documentation in this way? Because:

  • Technology is hard and every reader needs to experience patience and compassion during the learning process.
  • Growth is a mindset, and because anyone can learn anything if they’re encouraged to set aside judgment and open themselves up to guidance.
  • People want to relate to what they’re learning. Relating happens when someone reads a story, sees an experience through someone else’s eyes, or responds emotionally to content that provides something deeper and more meaningful than your average technical writing.
  • Compassionate technical writing is powerful. On a small scale, a delightful piece of doc could be the one bright spot in an admin’s otherwise harrowing day. On a larger scale, it has the potential to transform readers’ feelings and perceptions about what they’re capable of.
  • Compassionate technical writing also transforms the writer.  Compassionate technical writing requires you to keep in mind that real people are relying on your docs to get their jobs done. If you allow it to, writing in this way transforms you as the writer. It connects you with your readers. And that connection fosters the sense that your job is more than just a paycheck — what you write truly makes a difference.

Tips on How You Can Incorporate Compassionate Writing

  • Use real names to make your documentation more relatable. Instead of “A constituent makes a donation” try “Philando makes a donation.”
  • Be encouraging. After a very long list of setup instructions, one of our docs states: “Are you still with us? Congratulations, you made it to the last queue management setup task!”
  • Break up walls of text with graphics and bulleted lists. Compare these two ways to say the same thing. Which is easier to read?
    • Option 1
      • Some great techniques to break up long stretches of text are graphics and bulleted lists instead of writing really long paragraphs that go on and on and potentially visually tire the reader.
    • Option 2
      • How to break up long stretches of text:
        • Graphics
        • Bulleted lists
  • Don’t force it. Not every piece of technical writing will lend itself to “compassion” — so be judicious and don’t force it!

In closing, we all know that technology and our world are constantly changing and can be challenging at times. Technical writers can help bridge the gap and bring about a better understanding of not only the technology we are using but how to use that technology to make a positive difference in the world. Our hope is that our ideas will inspire you to identify ways that you and members of your team can produce content with a focus on humanity and empathy. The ultimate goal is to produce documentation that connects with the user on a deeper and more personal level. The user should feel, or at least experience some suggestion that the doc is talking directly to them.

We hope you are inspired to go forth and create and integrate compassion into your writing! For more information and examples, check out our Compassionate Technical Writing Guide.