July 2016
By Karina Lehrner-Mayer

Image: © Diogo Ferreira/123rf.com

Karina Lehrner-Mayer holds a degree in translation and has over 15 years’ experience in technical communication in Ireland and Austria. She works as a technical writer at ISIS Papyrus Europe AG, an Austrian-based company offering solutions for inbound and outbound business communications, where she is responsible for the documentation style guide.




Five tips for creating documentation that focuses on the user

Software documentation is not about describing each toolbar button and menu option. Smart technical writers help users. Here are some practical tips that let you zoom in on the people you write for, increase the quality of your user assistance and prove your value to the company.

As a technical writer with more than 15 years of experience, I still hesitate when people ask me what I do for a living. From experience, I know that a short answer conjures up a picture that is far from the truth. Still, I usually start with something along the lines of "I work in software documentation" or "I'm a technical writer". This usually entails a long pause and a questioning stare.

Then I fire away, covering all the exciting aspects of the job, from researching the software to designing diagrams, taking screenshots, writing style guides and preparing storyboards. "OK," the questioner goes, "so you describe all the menus and buttons?" Uh, no.

What I actually meant to say is: My job in technical writing is to help users do their job. I am a technical communicator.

And describing all of a program's buttons and menus rarely helps users. In fact, you can produce lots of pages of manuals and help topics without providing any benefit to the user, because this kind of documentation may not provide users with the clues they are looking for. Users don't look for descriptions of software features: they have a job to do, they need the software to do it, and sometimes they need assistance to do it.

While knowledge of the software solutions that we as technical writers are describing is an essential prerequisite, it is only one aspect of our work. Without knowing the people who use the program to do their work and achieve their goals, we cannot produce documentation that serves the user.


What do technical writers do?

Why we still think about technical writing more in terms of documentation than in terms of communication is perhaps due to traditional job descriptions such as this:
Technical writers use their language and information-development skills to document a piece of software for a defined audience. They know the software well because they played with it and interviewed the SMEs, while applying writing standards and mastering their Help authoring tool.

The description is not wrong as such and mentions users in the term "defined audience". But the focus is on the product and not on the users, thus missing the most important point: We shouldn't document, we should assist.

What should technical writers do?

Keeping your audience and its needs and goals in mind during the whole documentation creation process is what makes the difference.
The hard thing is to identify the users' needs and goals and what serves them best. Just looking at the program and documenting its functions won't do the trick. Sometimes we need to provide extensive information in the form of detailed examples. Sometimes we need to give short step-by-step instruction. Sometimes a video helps the most.

So, how do we find out what the users need? By communicating. From my experience I know that with the daily routine of work, the tight deadlines and demanding tools, it is easy to lose track of what technical writing is really about. But still, this is what we should aim for.


Getting closer to your users

At a time when everyone has to prove their value to the company, technical writers must do more than document the software. And let's face it: Everyone thinks they can write, anyway, so you must stand out by showing what else you can offer.
In this article, I have summarized some tips that have helped our documentation team to get to know our users better and, as a consequence, produce user assistance that better helps our users do their job.

It's not about adding another skill to your toolbox but about having an attitude that influences everything you do. It's about having a conversation: Listen to your users and find out what they need. Talk to users in a respectful way and give them the assistance they need.

How to focus on users

Here are five practical tips that help you focus on the people you write for:


1. Listen to your users and design personas.

This is the most important tip. Use every opportunity to meet your users and try to engage them in a conversation about how they work with user assistance. For example, I was able to get in-house users to participate in a workshop and ask them how they liked to search for information in our PDF user guides. Surprisingly, they told me that they use the index of the user guide. And this happened exactly at a time when the documentation team was seriously considering getting rid of the index in our documents.

Unfortunately, the documentation department is often far away from those who actually use the software in the real world. And this is why personas are so important: With a well-defined set of personas, you can keep user perspectives in mind when creating documentation for them.

Personas in software documentation
If you haven't thought about using personas in software documentation so far, start now.

Turn to the marketing department or the user experience team to receive relevant user information. If personas are based on customer surveys, marketing information, or other helpful data, they can give you a lot of insight into your readers' minds.

Personas are fictitious users based on valuable user research, usually consisting of a name and a motto, a picture, or a short bio with the most important goals.

Information relevant to documentation should be included as well – for example, if a single topic will meet the goals of all users, or what kind of language (e.g. non-technical) should be used.

Image: Example of a persona for user documentation

With distinct personas you may find out that you need to split up your documents, each addressing different user groups. Or you'll decide to include more examples, step-by-step instructions or more reference information. Once you know the goals of your users, you are ready to provide goal-oriented documentation.
We have been working with personas for quite some time, and we find it very helpful to sort out arguments and come to a decision by asking: What would Iris want?

2. Listen to co-workers who talk to your users, for example, the support team

Even when you use personas, you need to stay in contact with the real users to find out what the most urgent challenges with the product are. And who is better connected to the users than those who answer the phone or reply to emails sent by them?

Turn to the support team and ask them what makes up their daily work. This information may come as a surprise to you. Sometimes even looking at the number of support cases according to topics helps you find out where you need to act.

Use this information to update your personas, brush up the troubleshooting sections or to add specific topics to your documents that you had never thought of before.

In a recent project, we had meetings with the support team to discuss questions that came up frequently by users and how to address them. As a result, I investigated over 100 support cases in order to:

  • Find out if the relevant information was available in the documentation at all, and to make it easier to find and understand.
  •  Re-design and extend the troubleshooting section to reflect what users actually needed.
  • Cut lengthy text and leave only what was really important to lighten the reading load.
  • Find out if there was a need to improve the communication between product and user (see my last practical advice).

I was surprised to learn about aspects that were completely new to me, especially the kind of problems users have and how little text they are willing to absorb. Communication with the support team should be high on your agenda.

3. Speak to your readers in a clear language

Users want to do something, and you help them do it. Write as if you're talking to a real person standing next to you. Don't prepare a scientific abstract or create a marketing piece showing off buzzwords.

Use simple, clear, informal, direct, unambiguous language. Leave out everything that won't be of interest to the user but is in the document for other reasons (for example, because the engineer told you to include it).

Be precise. And learn how to cut a text until it contains only what is really important.

In close cooperation with the support team, we were able to cut the text of a standard email that is sent to customers by 50 percent. It's important to bear in mind that no one wants to read. Everyone wants a quick answer.

Typical pitfalls:
Watch out for phrases such as “it is recommended that”. These are often an indicator that you yourself don't exactly know what to say – because if you knew, you wouldn't recommend but say clearly why the user should do this or shouldn't do that.
Look out for passive constructions and rewrite them. Why say "the usage of this feature is not possible" when you can say "you cannot use this feature"?

4. Respect your users by applying a style guide

It should be only natural to respect your users by giving them consistency and standards in your assistance. Don't underestimate the irritation that ambiguous terminology or inconsistent formatting can cause for readers.

In your in-house style guide, address style issues in connection with the very specific users of your products. Don't forget to cover aspects such as screenshots and videos.

Apply the style guide, but be flexible
I am a firm believer in style guides. However, guidelines are a means to an end. And the bottom line is to write documentation that helps the reader. So, if your documentation style guide says, for example, that instructions shouldn't have more than seven steps, and you need more steps to assist the user in a specific task, add more. Helping your reader is more important than following the style guide. If you find that some rules must be bent more frequently, adapt the style guide rules.

When developing and maintaining a style guide, also keep the bigger picture in mind. The documentation you produce is part of a much larger package that users get from your company, such as the corporate website, newsletters, marketing brochures, and software.

5. Know when to suggest changes to the software

In some cases, helping the user by providing the right documentation becomes particularly hard. Sometimes the way the software communicates with the user is confusing, unexpected, inconsistent, or unnecessarily complex. As a technical writer, you know these situations.

This is the time when you need to take a deep breath and stop what you're doing. Remember the users (think "what would Iris do"), and compile a summary of your findings. Give your feedback to the developers, user experience team, or others who are in a position to improve the conversation of the software with the user.
Sometimes you are the first person in the development process to see a new function in context and not as an isolated feature. You might be tempted to try and solve the situation with your documentation skills: Giving more examples, extensive troubleshooting, and more Help topics. But do not give in. Respect your users by making their lives easier while they are actively using the software, before they have to consult the documentation or turn to the Help desk.



Yes, I may still call myself a technical writer and my work in software documentation still consists, to some extent, of writing or creating content.
However, software documentation is not about documenting the software, but about getting to know your users and helping them do their job.

Before you begin to design a new document or topic, before you start to write the first word, before you even sit down to discuss the latest features and functions of a program with an SME, think about the person who will be turning to your document or online Help. Think about how you can help this person. And then don't stop thinking about the person until you've finished your work.