Best Practices for Technical Writers

Creating user manuals is a difficult task on its own. Making them good is even more difficult. If while reading these first two sentences you thought to yourself, ‘Well, my technical documentation is quite good, actually’ - you might be missing an important point here: there is always room for improvement.

Stagnation inevitably leads to deterioration, so, you need to analyze user experience constantly and make the needed changes. Here’s a shortcut for you - get acquainted with the best practices we gathered in this article and see if you can apply some of them in your technical writing process.

Keep it Neutral

Although there is a tendency, especially among big companies who are working on their company image and character, to use a friendlier manner of communication with readers, and we are going to advise against this. A sense of humour is a highly subjective notion. Besides, some people just don’t have it!

As technical documentation plays an important role in case deflection, most people do not open a user manual for entertainment. And, as they are, most probably, facing some issue with your product, they are not in the mood to laugh. Some researches even show that people can consider humor in user manuals mocking. Just to be on the safe side - keep it formal.

Stop Reassuring

You might be surprised, but reassurance can create anxiety. Let’s take this sentence as an example: don’t worry, we will never give your personal data to anyone. Respondents say that they weren’t worried until they saw this ‘don’t worry’ part. Our brain just reads the word ‘worry’ and acts on it creating anxiety.

Simplify

This point depends a lot on your target audience, of course. Be especially careful if your manuals can be potentially read by non-native speakers. In a general sense, the wider your reader audience is the more simple the language should be. Let’s talk about software documentation. We should be mindful of the fact that people of different generations might read these manuals. Our parents/grandparents are using smartphones, too, so, if you are creating documentation for Apple/Android application, for example, you need to pay a lot of attention to the vocabulary you use. Take a look at the table below to see several examples of the preferred word choice.

Analyze Feedback

There are multiple ways of getting feedback on your technical documentation from readers to make some improvements later. Note: we are now talking about online user manuals.

So, the first thing you can do is analyze statistics. Our help authoring tool, ClickHelp, for example, offers both built-in statistics and Google Analytics integration. This way, you can track which help topics are getting more views and work harder on the most popular ones.

The second option is using a rating system for your help topics. This functionality is also available in ClickHelp. Review the ratings once in a while to figure out which topics should be restructured or rewritten.

The third way to get user feedback is enabling comments for help topics. You can integrate such services like Disqus into your documentation created in your help authoring tool. User comments can help you enhance your technical documentation, too.

Keep it Short and Precise

Longer sentences overcomplicate things. Always look for ways to make sentences more concise. Try avoiding constructions, like in the event that, just use if instead. To be able to is often used to denote the future form of the modal verb can - just use can for other tenses. Pay attention to any unreasonably long and heavy constructions and eliminate them. Another way to make any text more readable - try sticking to simple sentences. Make a couple of simple sentences out of the complex one.

Use Readability Score

Readability score services allow evaluating your texts to figure out how easy it will be for an average reader to comprehend them. Readability scores include different parameters for analysis. For examples, the service will count the percentage of terms in the text (the more terms you have, the less readable it is considered), sentence length, heading levels, etc. These and many other factors influence the final score the text gets. This might be extremely helpful for technical writers who are creating content in not their native tongue which hinders self evaluation. Check out this article on pros and cons of using readability scores in technical writing.

Conclusion

User experience keeps gaining momentum in technical writing. So, we advise that you pay attention to this matter. There are other ways to improve one’s user manuals that we didn’t mention in this article, of course. To figure them out, try analyzing more - some discoveries might be quite surprising if you try listening to readers’ opinions and keep learning about experience of other techcomm professionals. If you have any more help authoring tips to share, feel free to leave a comment below.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices