4 tips on writing user-friendly texts

In this article, you will find some tips on how to make your technical texts user-friendly and simple to read.

Say goodbye to pretty style

I’ll probably sound a bit harsh saying that, but technical writing is not about the beauty of language. When you write technical texts, your main goal is to make the text as understandable for the user as you can. That means you should avoid using or consider limiting structures like: 

  • Idioms, for example: If you don’t see the final screen, go back to the drawing board.
  • Unnecessary adjectives and adverbs, for example: Click this beautiful button to quickly go to the next step.
  • Phrasal verbs, for example: Click OK if you come across the following message.
  • Advanced sentence constructions, for example: Not only does this form allow you to enter your personal data, but also it lets you save it for future use.

As you can see, the “pretty” words in my examples, though a bit overexaggerated, don’t add any useful information. On the other hand, they make these sentences overly complicated and hard to understand for less advanced English speakers.

Avoid ambiguous words

Remember that very often software users are non-native English speakers. English is taught a bit differently in each country. While some words may be very natural for native English speakers, for non-native speakers they might have a totally different meaning. Of course, ideally, every language student should learn all of the meanings, but let’s be honest: is it even possible? My advice is to try and put yourself in your readers’ shoes and think about how they understand your word choice.

Here are some examples: 

  • “Since” meaning “because” – for many non-native English speakers the primary meaning of “since” is related to time rather than cause. 
  • “As” meaning “because” – many non-native English speakers use “as” mainly in comparisons. 
  • “For instance” – a bit extreme example, but if you use “for example”, you can be 100% sure that the users will understand correctly, so better be safe than sorry. 

Illustrate with examples 

Whenever you introduce a complex instruction, try to provide also an example of applying it in a real environment. You can use for example: 

  • Screenshot of a window with all fields with values (of course, use fake or obscured values). 
  • Step-by-step description of a particular use case (the main instruction has to be generic, here you can be much more specific). 
  • URL/directory/command example. You can provide the whole URL/directory/command even if it would be a bit different for each user. Just use <> for items that the user should replace with something else, for example:
    C:/Users/<YourUsername>/AppName
    Replace <Your Username> with your username.

Split a sentence if you can’t catch your breath 

Complex sentences make reading very hard for technical readers. Even regular readers sometimes struggle with them. However, if you use complex sentences to describe complex processes and procedures, it’s just a lethal combination. I would even venture a guess that it’s the main reason why so many people hate reading technical documentation and treat it as a last resort. 

Good practice to deal with it is to try and read your text aloud. If at some point you can’t catch your breath and the reading feels unnatural, then there’s probably a sentence to be reworked. 

My second piece of advice is to shorten or split your sentences whenever you’re in doubt. If you describe complex stuff, the users will prefer the sentences to be as simple as possible. In this way, they can spend time trying to understand the actual instructions and not what the writer had in mind. 

Here is an example of a sentence that is too complex and hard to follow: 

The configuration process enables you to select specific features in your application. To start the process, follow the steps below:
1. Click the Start button.
2. Follow the instructions provided on the screen until you see the Finish screen.
3. Close the configuration assistant.

Instead, you can convert it into a couple of sentences and a numbered list:

The configuration process enables you to select specific features in your application. To start the process, follow the steps below:
1. Click the Start button.
2. Follow the instructions provided on the screen until you see the Finish screen.
3. Close the configuration assistant.

Recommended Articles