by   |    |  Estimated reading time: 6 minutes  |  in Business Technology, Product and Innovation, Transform Your Business   |  tagged , , , , , , ,

Since its inception, documentation for software system users has been known as “help”. Fast-forward to today, when software companies now provide a wide range of user education material, including documentation, across various media, it is still important to think of this offering as help. Visualize your user education offering as the guiding hand extended by your company to your customers while they familiarize themselves with the software and navigate its complexities. 

Next, consider the situation when your customer will turn to your user education offering. It is likely they want help in the form of answering a question that they have about the software concerning the work that they are doing or, they want to know more about how they can get the software to work for them. This is when your user education offering can offer an outstanding “Moment Of Service.”  

Basic principles for creating content geared towards the Moment Of Service 

Use your software 

Prior to content creation, put yourself in your user’s shoes. This brings us to an essential aspect of documentation, often discussed within technical writing circles: user empathy. The implications of an empathetic approach to documentation are far-reaching and extend to how you formulate documentation, how clearly you write, and how well you organize your content.  

Knowing how to start writing can be tricky, but it does not have to be. 

Use your software from beginning to end and document it in a similar fashion 

The importance of knowing your software and testing the effectiveness of your writing is critical. Not only does this ensure that you provide your users with facts and the sequence of how the software works, but framing your story this way positions you to answer questions the way a user would and answer them via your documentation.  

Focus on your user 

During content creation, it is easy to get wrapped up in the notion that the content’s focus must be on the software produced and describing it from the software point of view. This is not the case. Your content must be focused on your user.  

Use “you” and “your” where appropriate to address your user directly  

Not only does this help your user find answers to questions they have or know how they can get on with a task they are performing, but it also creates underlying value in that the content feels relatable, makes them feel seen and is personal.  

Keep it clear 

Consider a user landing on a page hoping to find the information they need, reading it and coming away confused or not having found what they were looking for. Pretty frustrating, right? When your documentation lacks clarity, it fails to be as useful as intended. 

Clarity in documentation can be achieved in multiple ways, a few of which are listed below. Firstly, present an outline before you get into the meat of content-heavy topics.  

Set the stage for what you are about to detail before you detail it 

Another way to increase clarity in documentation is to use active voice instead of passive voice. Often the cardinal rule of technical writing, it is not hard to see why. Using the active voice emphasizes the subject, in this case, your user, as opposed to passive voice where the subject is unknown or unstated.  

Finally, to round off on ensuring clarity in your documentation, be sure to incorporate both functional and linguistic reviews.  

Reviews are integral to your documentation process 

They not only help verify that your written content is accurate but are a good yardstick of how well your documentation is received by another person.  

Keep it simple 

Going back to when your customer is looking through your documentation. Often, this is when they are keen to finish a task and move on to the next job on their to-do list. Cue a long, unnecessarily complex document, and you miss delivering a stellar moment of service. 

As technical communicators, we are often guilty of documenting too much, which can be as damaging as documenting too little. Keep in mind readers of documentation have varying attention spans and different degrees of comprehension. By keeping your documentation simple, you can cater to all these users and leave no one behind.  

 Keep users interested in what you have to say with minimalism and chunking 

Ask yourself if the content you are about to present is essential to the task at hand or if it is a supporting detail that would be best relegated to another topic. For example: Your task is to describe how to get a user from Point A to Point B; you should include information on points of interest along the route in another topic. 

You may also use visuals where they aid understanding, and break up the monotony of text, while appreciating that text contained in images is not easily translated. Images must be constantly updated if they are taken from a product with a frequently changing user interface.  

Keep it consistent  

Applying templates and style guides to your education offering helps you achieve a degree of consistency and predictability that users undoubtedly appreciate. While as technical communicators we may take the several styles such as headings, tables, and bullets for granted, but these visual elements contribute significantly to increasing the readability of a document. 

You can also introduce consistency in the tone of your document by employing repetitive sentence structure or parallel syntax. Parallel syntax allows readers to pick up information without extra cognitive effort and commit information to memory.  

Allow users to become familiar with the tone and voice of your document 

Not only is this predictability nice-to-have, but it also lends itself to the empathetic route.  


While user education material may not be quite the cause for excitement, well-crafted material contributes to the heart of a service culture, where anticipating your users’ needs and producing content with a service mindset, the right information is available at the right time, fulfilling a moment of service. 

Want to solve complex technical issues and bring solutions?   

Join IFS today: 

Do you have questions or comments?

We’d love to hear them so please leave us a message below.

Follow us on social media for the latest blog posts, and industry and IFS news!

LinkedIn | Twitter | Facebook | Instagram

Leave a Reply

Your email address will not be published. Required fields are marked *