How to ensure your technical documentation works

A recent blog post by my colleague Danny, 5 reasons why product documentation is the marketing department’s secret weapon, expertly laid out the reasons why marketing departments should harness the full power of technical documentation.

But what about you, the technical communicator? What are you doing to ensure your user gets the most from your documentation? Producing high-quality, factually correct documents is great, but how effective are they really, if you fall at the first hurdle: getting your users to read them?! The test for truly effective documentation is usability.

This article outlines how to create documentation that reaches your intended audience, and then how to check that same documentation is effective.

What makes excellent technical documentation?

Technical documentation is about guiding the reader; leading them from where they are to where they want to be; from a problem to a solution. At 3di, we call that “Complexity made clear”. Good technical documents contain all the information a user needs. But excellent documents present this information to them in a way that is easy to understand and easy to find. This includes everything from the style and tone of writing, to the number of pictures and diagrams used, to what type of media the documentation is produced in and the layout on the page or screen.

So how do you decide on these things? Well, you have to get to know your audience. Once you understand who they are, what motivates them to read and what they want your documentation to help them achieve, you can ensure that your documents help them reach solutions quickly and efficiently.

How to create documentation that reaches your audience

Ok, great, you know what makes documentation excellent. Now let’s turn that knowledge into optimised documentation! (Top tip: if you’re not sure you know your audience or their needs well enough yet, you could try some of the activities later in this blog, under “How to check that your documentation is effective”.)

Include just the right amount of information

Remember, we’re leading the user to a solution here. This documentation isn’t an excuse to write thousands of pages demonstrating how much you know about the subject. Keep the information relevant to the user that you’re writing for, bearing in mind what message you’re trying to convey. This is why equipment often has separate operation and servicing manuals.

Get the balance right between concepts and tasks

Typically, good technical documentation is for getting the most from the product. That first means helping users understand the product, and then supporting them to achieve tasks. However, you can’t know for sure what each user will be trying to achieve, so you need a flexible mix of content types (Concepts and Tasks for example) that you can organise to suit your most likely user situations. If in doubt, or if you have got limited time, focus on Concepts and the most common or least intuitive Tasks. The better the user understands the underlying concepts of the product, the better equipped they will be to achieve tasks unsupported. Also recognise that many users learn through repetition, so it can be really valuable to have a number of ways of understanding key concepts or the trickiest tasks; by combining text and graphics and videos, and even embedding the same content into the product interface if you can.

Remember that this is a customer-focused, problem-solving approach. Consider who your documentation is aimed at. Service engineers? Operators? The public? Different types of end-users are looking for different types of solutions to different problems, and their level of understanding and interest will vary. To address the variety of audiences, the level of detail in your documentation needs to be different, depending on who it is aimed at.

Get the words right

Individual words can be very powerful enablers or get in the way of understanding, so be consistent with the terminology, and make sure different teams in the business know what words to use for the same feature or concept. For example, if your customer has been sent an email about steps for “onboarding”, then it’s not very helpful if the documentation uses the term “implementation” for all the information about these steps. As a technical writer, you could provide a valuable service to the business by curating a shared terminology database or glossary.

Lastly, regardless of the audience, don’t use jargon. Let’s keep things as simple as possible and remember why we’re here: making complexity clear.

Structure your technical documentation to make updating easy

Ensuring documentation is easy to update will help you incorporate feedback or react to product updates promptly. 3di has years of experience using the tools and techniques to achieve this and uses them every day. For example, we use modular information design combined with tools that allow us to update information in a single place and have that update published to all the places it needs to be used. These tools mean that, big or small, changes are easy for us to make and ensure they’re accurate, whether it affects one web page or hundreds of PDF pages.

Make your content easy to find and navigate

The first step of usability is findability. What constitutes “findability”? Well, that depends on your product and, more importantly, yeah you guessed it, your audience.

Ask yourself these questions when designing your documentation:

• Where are my users when they need information? – If they’re at a roadside servicing a traffic light, users probably need access to information on a phone or tablet. Preferably, this will be downloaded because roadside traffic lights are often in places without a guaranteed mobile signal. For this, a PDF or a help app might be the best format. If the user is sitting at their desk, using the application they need help with, then built-in user assistance that puts help directly into the UI might be the best option.
• What relationships or groupings do my audience expect in the information? – Is there an order that users must do the tasks? Is there information they need before they log in for the first time? Do users need to look up detailed reference information? Organising information is tricky. One thing we know from information design and usability testing is that one person’s understanding of a “logical” structure is completely different from another. But starting with the user’s understanding (rather than the author’s or product creator’s) gives a much better chance of success. One way to approach designing this structure is card sorting. Card sorting is a method of designing or evaluating how information is organised by asking users to organise topics, written on cards, into groups. This activity gives you insight into their understanding of the information, which you can then use to design your document structure and therefore optimise navigation for your user.
• How obvious is the information on the page? – It’s easy to forget that getting users to the right page doesn’t mean they’ve found the information they need. Use meaningful titles and sub-headings to help them find the section, table or diagram that holds the information they’re looking for. And don’t forget whitespace, lots of whitespace. These features all help break up the information, making it easier to navigate and understand.
• Is my technical documentation optimised for search? – If your documentation is an app, HTML or PDF, users will be using the search tool. This means it’s important that you understand and apply the same terminology as users. Get some insight from your customer support or technical implementation colleagues about what words customers use when they are asking for help. For example, if you’re writing documentation about logging into an app and the user wants to learn about passwords, use the word “password”, and not “credentials”.

For more information on how to improve the user experience of your documentation, my colleague Barbara Kujawska has written a great article called ‘(UX) Writing the docs’ which can give you some more handy tips

How to check that your technical documentation is effective

A technical document is often an ever-evolving entity, just like the product or service that it accompanies. An author’s job isn’t done just because the documentation has been delivered. Consider measuring the success of your documentation by collecting feedback from the customer and/or documentation user. Constant feedback ensures that your documentation is always evolving and serving your customers’ best interests. These are some of the ways that we, at 3di, evaluate the effectiveness of our documentation:

• Regular calls with a product manager – Set up a regular meeting with a product support manager or product manager. These people have access to channels for gathering user feedback and they know about common questions that users have.
• Analytics – If your documentation is a web portal or an app, analytics such as Google Analytics are useful for learning about how your online documentation is being used. For example, insight into what users are searching for is a very powerful tool.
• Built-in feedback – For online documentation, make it easy for users to leave feedback. This may be a text box on every page for detailed feedback, or just simple thumbs up/thumbs down buttons. This is easy to implement and can provide useful information for you because it captures feedback at the exact point that the user is having trouble.
• Usability testing – Ask real users or people with the same profile as real users to complete tasks that require them to use your information. This provides invaluable insight into what it’s really like.
• User interviews – Try to speak directly with some users of your new documentation. Ask them specific questions such as what they last tried to find out from the documentation, and what that experience was like.

To sum up

Hopefully, this blog post has helped highlight just how important it is to take a user-focused approach to your documentation, and you’ve picked up on a few interesting points that will help you with your future writing. While technical documentation can serve many purposes, it can’t do any good unless it’s easily found, accessed and understood by the intended reader. Technical writers have a big influence over these factors.

And, if you only remember one thing from this article, it’s this: keeping your user in mind whilst designing, creating and reviewing your content can help you turn good documentation into excellent documentation.