How to ensure your technical documentation works
by Matt Rus
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.
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.
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”.)
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.
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.
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.
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.
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:
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
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:
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.
Matt is a Junior Technical Author at 3di. Matt is a very technically minded person and enjoys finding out how complex products and processes work, and then conveying this information as efficiently as possible. When Matt isn’t busy sleeping, eating or authoring, he can be found cycling, and often competes in amateur races.