to top
← To posts list

7 Rules for Brilliant UX Documentation

Posted by ClickHelp TeamClickHelp Teamin Documentation UX on 12/10/2019 — 2 minute read

man working in front of computer banner

UX as a term is used more often when talking about user interfaces, but it can be applied to any object a human can interact with. Being an important part of the user journey, technical documentation deserves a special mention in terms of UX. Today, we will give you several tips to make your user manual UX not less than brilliant!

Put Creativity on a Leash

It is important to differentiate between texts that serve various purposes – this will be your starting point in achieving better UX. Quite often, writing a lot leads to a unique writing style being born. While this is not a bad thing in general, it can interfere with high-quality help authoring – remember, there’s no ‘I’ in user manuals. Meaning that applying creativity and stylistic devices will be redundant most of the time. Getting a clear message across is the goal of technical writing, sticking to it will be the wisest choice.

Minimalism is Good

Getting rid of other forms of redundancy helps keeping tech docs clear and concise. Eliminate all extra words, make sentences straightforward – no water, no possibly misleading phrases. Ideally, your instructions should contain minimal words, just enough for a reader to follow through.

Don’t Go Over the Top with Jargon

Whether to use jargon or not depends on your target audience. But, anyway, this is an important thing to mention here. Using professional terminology too much makes a text look unfriendly, keep that in mind.


Consistency is the cornerstone of good UX writing. It gets harder to maintain it when the documentation projects become bigger and the team grows. However, creating style guides/glossaries will help with that. Remember that calling the same things different names throughout one user manual is going to be extremely confusing for readers.

ux templates on screen

Emotions Go After Facts

We did say that being creative is not appropriate in help topics most of the time. Let’s talk about when it can be OK to add emoticons to dry technical text. Sometimes, companies prefer to keep virtual conversations with users in a friendly manner, some of this attitude can influence documentation, as well. The rule of thumb to follow – facts and important information come first, emotions – later.

Add Visual Elements

Of course, not everything is so easily explainable through words. Oftentimes, readers need something other than that to digest information. Especially when we are talking about highly complex technical documents. To improve UX in this case, you need to think of visual content that will fit in with the topic in question – schemes, more screenshots, graphs, videos – anything works as long it helps readers.

Make the Most of Your HAT

Take advantage of the features your software for technical writing provides. They can become the shortcuts you need to minimize time and effort and make UX better. These can be premade elements like information and warning boxes or navigation elements like mini-TOCs, breadcrumbs, etc.


Applying these rules in your help authoring will take UX to the next level. Let us know in the comments below any tricks you personally use for creating brilliant UX!

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

Give it a Try!

Request a free trial to discover the ClickHelp features!
Start Free Trial

Want to become a better professional?

Get monthly digest on technical writing, UX and web design, overviews of useful free resources and much more.

"*" indicates required fields

Like this post? Share it with others: