Meet my tips for writing useful documentation that your users will read gladly.

Prepare to Write Documentation

The first step is preparation – on this step, you should:

• interview SMEs to learn more about the product;
• talk to a support team to learn what questions are popular among your users;
• read documentation of a similar product, if possible;
• write your first draft;

Start Simple

When you finish your preparations, just start writing. Creating a starting point can be enough for you to start writing documentation and not procrastinate since the file is already open, it’s no huge step to contribute something now.

Moreover, as you’ve just started, there is no need to add visual content like diagrams, images, graphics and the like immediately. It doesn’t all have to be there from the start. As many tech writers try to add the elements immediately, it can become a stumbling block and a tech writer can be stuck on this step. Screenshots can be also unnecessary, you can add them later, for example, while testing your documentation.

Humanize Your Work

Recently, I saw a question on Facebook: “What is better to use — ‘user’ or ‘you’?” And my next tip is humanizing your text. Nowadays, the best choice is to use ‘you’.

Another tip is to create text for people. Unfortunately, some user manuals are hard to read and I wonder if there really was a human or a computer that made that manual. Of course, documentation is not a colorful novel, but you can humanize your document with some of your personality, so that a reader will feel a little more comfortable while reading it.

If you’re not sure, whether your users will understand your document or not, use the readability metrics, you can learn more about them here: Readability Metrics and Technical Writing.

Give Examples

You can humanize your documentation via adding examples. Examples also help users to get the main idea quickly even if a topic is difficult. Here is an example that I got from ClickHelp manual:

Maybe, you know how the wildcard search works but an example makes it more clear for beginners. Otherwise, if your audiences are different and you want to hide such obvious examples for experienced users, you can use conditional content blocks. You can learn more about this feature here: Conditional Content.

Test Your Documentation

When you finish writing, test your documentation before sending it to your reviewers — follow the described steps by yourself or ask your team members to do this. If someone asks you a question, you should immediately improve the part that was unclear. Of course, you can explain that part to your team member who tests your document but you can’t explain it to every user — they will just ask your support team. In order to reduce costs on support, just describe the unclear parts every time you’re asked questions.

What are your tips for writing useful documentation?