Documentation

8 Tips for Writing Great End-User Documentation

Jan Musil
August 31, 2021 | 7.5 min read
Why should we focus on the end-user documentation? Well-structured user-friendly product documentation can mean the difference between a fantastic customer experience and a terrible one. You must understand that user documentation is not just for new users, but it is also for experienced customers because they may want to refer to the documentation for new guidance or just to refresh their memories on a feature they haven’t used often.

But there are more reasons why you should focus on the end user documentation. Great documentation benefits from:

  • Guiding new and experienced users about software usage – end-user documentation is usually the first place where users look when they have questions. Customers will be more satisfied if they can search the documentation and find an immediate answer to their question rather than waiting for a response from customer support.

  • Reduce your support costs – each time the end user finds an answer in the documentation they do not need to call your support team.

  • Important marketing tools – it is more than just a set of how-to procedures. It’s part of the customer experience and that means it is also marketing materials.

  • Improve company image - great user documentation shows your customers that you care not just about them buying your product but that they also have a truly great experience using it.

Even though each product is basically unique, and it will require specific instructional elements, there are some best practices that should be followed when creating user documentation:

1. Use plain language

Nothing is more frustrating to customers than reading something they cannot understand. Use simple, plain language whenever possible, to help your customers understand even the most complex concepts.

2. Keep it simple

Keep the documentation as simple as possible. Remember, you are creating documentation for end users of all skill levels, not just developers.

3. Use visuals over wording

Do you know the adage “show, don’t tell”? Well, visual content within the documentation, including images and videos, quickly shows someone how your product works. While strong writing and text is essential for all user documentation, people learn best when visuals are also present.

4. Focus on solving problems

Rather than describing a feature because we all love our new feature, you should tell customers how to solve their problems with it – how this cool new feature will help them with their work.

5. Create a table of contents

To be able to quickly find a solution, a table of contents must be a part of all documentation. It should include all the major headings and subheadings as described above.

6. Searchable content

Nowadays, customers are accustomed to finding the answers to their questions by typing them into a search box. Searchable content gives users easier access to your content and helps them find solutions on their own.

7. Show examples and end results

Customers need to know what successfully completing tasks should look like. Providing customers with a screenshot of an example result is an ideal way to demonstrate the outcome to your audience.

8. Use step-by-step instructions

Try to avoid long blocks of text and use step-by-step instructions to provide a much clearer way to show a process than trying to explain it via text alone. Step-by-step guides are easier to follow, easier to understand, and offer a much more user-friendly experience than simply telling someone how to complete a task.

Example step-by-step instructions screenshot for Data Structures documentation | Accurity data intelligence software platform | Business Glossary and Data Catalog solution

All the points above are the most important methods for writing well-structured documentation. However, if this is not enough for you, we have some more additional hints and tips…

When writing a user guide, you should stick to the following rules and advice:

  • The technical level should be tailored to the specific audience that the manual is written for e.g., administrators or end users.

  • Always speak to your audience in terms that they will understand.

  • Do not assume that the user has prior experience or product knowledge.

  • The user manual should follow the steps of how the product should be used.

  • Any technical writing focuses on user tasks and the concepts that support the tasks.

  • Organize all information hierarchically.

  • Try to think like a user.

  • Always write in the present tense.

  • Always use an active voice i.e., do not use passive, but active voice.

  • Always use the “you” gender when speaking to users – it is better to focus on them.

  • Present any instructions as step-by-step procedures.

  • Use numbered lists for instructions unless the instruction is a single step.

  • Use the If-Then approach.

  • Start each step with an imperative word such as “Enter”, “Click”, “Tap”, “Select”, etc.

  • Use pictures and diagrams as effectively as possible within the guide.

  • Try to avoid lengthy paragraphs.

  • Explain what functions or features are for.

  • Ask somebody to proofread the documentation before publishing it. Proofread all documentation and all revisions.

There are additional reasons why a review is so important:

  • To find errors and problematic instructions.

  • To discover opportunities for improvement that the original writer may have missed.

  • To deliver defect-free, well-prepared documentation.

  • To teach colleagues and share knowledge.

  • To double-check the language used e.g., (American) English, because not everyone is a native speaker/writer of the language you are using.

  • To prevent abuse/misuse.

Our Accurity team is trying to focus on every single element of our user documentation. We know that user documentation is one of the key essentials that must be provided to customers with every release to ensure proper customer satisfaction.

Have you read our product documentation? Do you think that we follow all the rules mentioned above? Is this blog still not enough and you would like to know more about documentation? Do you have a different experience with user documentation writing? Do you disagree with me?

If you answered any or all of the questions, then perhaps you may want to check out our open positions and maybe one day soon, we can cooperate as colleagues 😊

Jan Musil
Operations Manager