June 3, 2021

How to write a successful user document in four simple steps

Having been a test consultant for several years I regularly have to familiarize myself with a new testing tool or solution. Since joining Infuse this has been my company’s own scriptless test automation tool useMango™. The quickest and easiest way to upskill yourself when it comes to handling new solutions is by reading their respective user documentation. I have seen my share of well-written as well as horrible user docs in my time, and while useMango’s™ were good, I jumped the chance to have my say on the latest release notes for version 5.1.

You find that many user documents lack proper structure, assuming you already have adequate knowledge about their given tool or service. This causes them more often than not to skip the basics. I am sure many of you reading this have come across such situations where despite addressing the user doc you simply couldn’t find the right answers when you started learning about an application. It isn’t just about showing the writers in depth knowledge of the product but presenting every facet of solution in a formulated and concise manner to the reader.

With my relevant experience using useMango™ and having written numerous papers throughout my career, I was confident about how to approach writing about the different aspects of the solution. The tricky part is when you know so much about a product that now seems second nature, how to not present it as too convoluted to a novice reader. You need to make sure you don’t make assumptions, the user most likely knows little to nothing about your product. They could be new to the Industry as a whole, so try your best not to show off about how knowledgeable you are, but constantly remind yourself and unknowledgeable they may be about the topic.

Here are my 4 simple steps to writing a good user document.

Step 1:  Re-review the solution

It doesn’t matter if you have been given the ominous task of writing a user doc for a solution you hardly know, or one you could operate in your sleep, make sure you re familiarize yourself with each feature before you write about it. You don’t want to be the individual talking about features from a previous version of the software that has now been moved, changed or even removed! Don’t be afraid to go to the developers to verify something either, remember they most likely know a lot more than you do!

Step 2: Make sure you modulate

Breakdown your content into small bites or ‘modules.’ Throwing huge volumes of information at the user could easily overwhelm them, making them unlikely to actually read the documentation and possibly even find a more reader friendly solution. Divide up your knowledge into a logical hierarchy, a structured path on how to approach the application, providing related resources as a great way to supplement basic training with more complicated matters, if they are so inclined.

Step 3: K.I.S.S (Keep it simple stupid!)

As much as people love watching computer programmers or hackers in the cinema hitting keys at an alarming rate while spewing our enough acronyms to fill their own dictionary, the reality is a little less dramatic. In fact, the reader will appreciate it far more if you do the exact opposite. Keep the language plain and simple, if you do need to use an acronym, make sure you say the full sentence first either before or after (see my heading as an example) and if necessary, explain what it means. Be sure to incorporate visuals into your work where you can. Using screenshots as landmarks in your documentation make is that much easier to follow and trust me, your users will thank you for it.

Step 4: Success is a two-way street

As with any successful product, documentation will need to be constantly re-revised and updated to make sure it stays relevant. Providing tips or suggestions in segments is always a crowd pleaser, especially if users are on different versions of a solution (remember what I said in step 1 about certain aspects being changed or moved). This means you wont need to re-write an entire document each time, but just let people know if one small aspect has changed. Feedback on your work from the developers who helped create the product is invaluable as well, but so too is feedback from the users themselves. There is no better way to increase your reputation for customer service them by listening and adjusting your writing to the users needs (FAQ’s & customer support details in your documentation are a great way to do this!)

A successful user doc is more than a technical advantage

A good user manual is not just a benefit to your business from a technical point of view, but will also have a positive knock on effect to your companies image. If you can easily provide the answers that your users are seeking in your documents, not only will you see a reduction in support call, pressure on your support teams and customer churn, you will be inspiring confidence in your users to keep using your solution.

Watergates Building, 
109 Coleman Road, 
Leicester, 
LE5 4LE

Tel: 020 3303 0581
linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram