Technically writing with empathy
By: Alexandra Gifuni
Tags: Documentation, Technical Communication, User Experience, UX, Writing Tips

How do you write with empathy when what you write is technical documentation?

By broad perception, technical documentation is dry and devoid of much personality. In reality, well — OK it is pretty much that.

Writing in this field means keeping things simple and concise, while ensuring that the voice and tone of your writing remains neutral. You often need to follow content guidelines, are loaded with work, and have to deal with tight deadlines. On some days it feels like you are just powering through a task as quickly as possible so you can mark it done and start the next one.

So it becomes really difficult, as a mental exercise, to associate empathy with technical documentation.

To answer the question of “how to write with empathy?” then, you need to think about the basic purpose of what you are writing. That purpose is to help whoever is reading your work to complete a job, whatever that job may be. The user is somewhere in the process, and you need to get them past the finish line. So every time you sit in front of your computer to write down, illustrate, or map out a document for them, you need to ask yourself if what you are documenting is truly helpful for that user.

Here are some pointers to help you get there:

Never take for granted that you “know” the product

No matter how long you have been working with your product, you should always write like you are learning how to use it for the first time. The best way to do this, of course, is to test your steps.

Here is my suggestion; Once you finish writing an article, put it aside. Move on to your next task, go for lunch, chat with colleagues, or whatever gets your mind fully off the article for a while. Once a few hours have passed, return to it. Open your article up, and have your product ready (I work with a SaaS company, so I have my product open on one screen, and my article on another). Now go through the process outlined in your article step-by-step.

You’d be surprised at how often you’ll find you unintendedly skipped an essential instruction, or wrote something in a way that might not be clear for someone who is less familiar with the product.

This is also a great opportunity to think about the kind of questions the user might have while following your article. For instance, if you have a step that tells the user to connect to their account, link to the page that explains how to connect. Don’t take for granted that the user knows how to do it, or assume they can just as easily find the page on their own.

Send out your work to a colleague for review

As writers, there are times we spin our wheels over one article for so long the words seem to lose all meaning. It is precisely at this moment that reaching out for help is the best thing you could do to ensure that your documented process makes sense. If you work with another writer — great — ask them to give your article a review. If not, Support people, UX writers, and product developers are all your allies on this. They engage with the customers through their work. Like you, empathy is on the forefront of their minds within their everyday jobs. They will be able to help you review your article, and should be able to let you know if there is any portion of it that doesn’t answer to the customer’s needs.

Of course, in the spirit of empathy it is good to remember that your colleagues are just as busy as you. So when you send out work for review, it’s always best to be clear on what you need. Let your colleague know you just need them to help ensure the steps makes sense, or ask them if there’s anything they would add based on their experience with that error/feature/so on. They will be a lot more willing to help once they know you’re asking for a review specifically based on their expertise.

Think about what situation your user is in when reading your documentation

When I look at Google Analytics to analyze our help center metrics, I can see with a few clicks that our most read articles are related to error troubleshooting, and that the majority of our users are reading those articles on their desktop computer.

So how does this help me, exactly?

Well, it tells me that I can safely say our user is in a home or office setting, able to view the articles on a comfortably large display. This means that I can write longer, more detailed articles. I can even include larger screenshots, because I don’t need to worry about how they’ll be displayed. I also know that writing longer articles with screenshots is probably a good strategy since our product can be complex. Our user appreciates details when they are trying to find a workaround to an issue. They don’t necessarily mind a bit of reading if it means they get to move on and finish the job.

That might not be the case for your user, depending on the kind of product you sell. Take an app that gives directions. Imagine the user needs help because they can’t get their GPS to calibrate while using it. There is a very good chance they are in their car, stressed, and viewing the troubleshooting instructions on a small phone screen. The last thing they need to worry about is reading a long form article with screenshots that don’t display properly. Instructions need to be optimized for their situation.

That is why empathy isn’t just about content, it’s also about the user experience. So, when managing the documentation, consider the following about your user:

Where are they located?

Like I said, a user sitting at their computer might have a different patience threshold than one sitting in a high-stress situation.

How are they reading your articles (computer, mobile, tablet)?

Your articles should be readable across all devices, but you need to focus on optimizing articles for the most popular one.

Is your help center easy to access?

Ensure there is an easy-to-spot link on your main website to the help documentation. Your articles should also come up as the top results when searching organically. To verify this, visit your favorite search engine, like Google (obviously), and type key words or phrases associated with your product. If there are no results associated to your articles, or the results are being pushed down by third-party sites, work with the SEO specialist in your team to see how you can improve things.

Are the most popular search terms bringing up the right results?