airfocus-logoProduct Learn

✏️

Become a writer

25 Apr 2022

How To Write Technical Documentation

Product Strategy
Contents
airfocus eBook All You Need To Know About Product Management
Get our All You Need To Know About Product Management eBook
Read now

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:

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. 

How to write technical documentation

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:

  1. To let the user know upfront what they will expect.

  2. 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 to write technical documentation

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.

Read also

31 Aug 2022

Company Vision vs. Product Vision - How To Align Them

20 Sep 2022

Product Discovery – A Product Managers Guide on Discovery Processes in Product Development - Part 1
working-together-white
Kent McDonald5 Oct 2021
Working With Your Product Development Team

Define a strong well-communicated product strategy

Join thousands of teams who use our flexible product management platform to build products that matter.

Try for free

Book a demo

airfocus coin
Top rated
on major review platforms
g2 badge users love us
g2 badge leader summer
GetApp badge category leader
software advice badge
capterra shortlist badge
proddy badge roadmapping
crozdesk badge
Company
All rights reserved. contact@airfocus.com
ENDE