Writing technical documentation is hard.
The reality is, most people won’t really be compelled to read it in the first place. We all lead busy lives, and who has the time to read through hundreds of how-to documents?
And yet.. We all have them and we all use them. So how do you get people to actually read your technical docs and get the most out of them?
After years of being a technical writer, I’ve got a few tricks up my sleeve I want to share.
Focus on the problem
The most boring documentation is that which tells you how to do things, but not what you are doing and why.
Most people don’t really need a step-by-step on how to click on a button, we all know how to click on a button!
Make sure you’re adding focus to the following:
Why the problem is being solved
How you’re solving the problem
Treat your documentation as a product, not a process. Just as if you were presenting features within your product, you are now presenting features within your product *documentation.*
Introduce the different parts of your product as a strategic piece to your customer development, not as an afterthought.
Documentation is not a UX replacement
You don’t need a document for every action or button in your product. If you think that’s the case, there’s a much larger UX problem at hand.
Documentation is there to help people understand what they are doing and why - with some guidance as to how - but nobody needs a rundown of button clicking.
Outline the benefits of actions being taken. Why does this feature exist? How can your users get the most out of it?
This will help reduce the learning curve and ensure that users are understanding the value of your product, not just the expected output of an interaction.
Set up a template
If you really want users to read your documentation, you have to approach this with a very simple thought in mind: they won’t read, but they will skim read.
Optimize your documents to follow a structure that will develop a mental pattern for them, so that they know where to go if they’re looking for something specific.
Here’s a template I like to work with:
Benefit of the module
Anchor links to the rest of the doc
Permissions available
How the module works
Videos
Further reading
Benefit of the module
This is your ‘what and why.’ What problem does this feature or area of the product solve, and why should someone want to use it? What is unique about it, and what are the expected outcomes?
It’s important to add this preamble for a couple of reasons:
To let the user know upfront what they will expect.
There is such a thing as support-led growth, so you may inadvertently be selling an upgrade here!
Treat all documentation as a way to inform potential leads as well as existing customers. Always reinforce that this is the right product for them, and that they will reach their desired outcomes.
Anchor links
All is good and well until you end up with a doc that’s 1000+ words long. That’s a blog post right there!
Now length isn’t an issue, unless it makes the document very difficult to navigate.
In order to avoid overwhelming the reader, create some quick anchor links to different sections. This will help the user get around, but will also help create a mental model for the rest of the docs, making them more efficient.
How the module works
This is essentially your how-to. Nothing wrong with adding step-by-step instructions here, it’s what they came for.
Videos and Further Reading
If there are any supplementary videos you can provide, this is the place for it. These could be short 2-min videos, webinars on how to use the feature, or even marketing videos.
It’s important to understand that people learn in different ways, so providing another medium like audio or video will be an added benefit.
You could also provide further reading, like related documents, or blog posts where the product or feature may have been highlighted.
Again, this is about reinforcing the benefits and creating an experience for the user outside of just the existing how-to.
Write in short sentences
As I said earlier, people don’t read, but they do skim read.
Make sure that you write in clear, concise sentences and simple headers. When guiding through to find an area, use bullet points (ordered or unordered, your choice!) so the directions are easy to follow.
While we’re on the topic of writing, I like to make sure content is both accessible and inclusive.
This is not the time for clever wordplay. While storytelling is still an important aspect for the user experience, stick to writing that is easily understood.
Vocabulary matters, so try to avoid pronouns where possible. In education material I like to stick to “you” or “yours” to make it personal and add a little more empathy to the fact that the user came to this particular document for help.
Documentation is always evolving
As long as your product is evolving and iterating, so is your documentation. You are never simply “done.”
Earlier I mentioned treating your documentation as a product. As such, make sure you are learning, experimenting, growing, and evolving your documentation. Seek for feedback and find ways to make it easier to use, more accessible to find, and beneficial to the customer’s journey.
Your product documentation and resources should (and will) grow with the maturity of your product and your customers, while remaining inclusive and adaptable to their journey.
Andrea Saez
Read also
Create effective product strategy
