Skip to content

Writing documentation that users love#

Hard-to-read documentation makes it easy for users to hate your product.

Why? Well, documentation is an essential part of product UX. I'd even say documentation is a product of its own. So, it's important to give it some love and perfect it like you'd do for the product itself.

But, how do you write documentation that users like?

1. Start by asking what the users want#

Do they want to configure something? Are they looking for info on your new feature? Do they want to learn how to use your API? See, all these questions will result in vastly different pieces of task-oriented documentation.

Task-oriented documentation is user-centric documentation since the technical writer does the thinking for the user.

As a technical writer, my mission is to help users become better at their jobs. It's not to sell the product but to help users use the product in a way that makes their lives easier.

Tl; Dr: User is the main character and docs play a supporting role.

2. Apply the 5 C's#

These 5 C's pretty much capture the essence of docs that users rave about:

  1. Clear: Describe the task at hand in simple language. After reading the documentation, the user should feel confident performing the task. Confusing the users only results in frustration and angry support tickets.

  2. Concise: Snip the verbose and keep the docs short wherever possible. Most users scan instead of reading. Focus on brevity and scannability of the documentation.

  3. Consistent: Make sure that you're using similar terminology across your docs. This reduces the cognitive load on users to decide/understand multiple different terms that mean the same thing.

  4. Complete: Good documentation is exhaustive. It doesn't miss out on the details that the users need to know to successfully complete the tasks.

  5. Contextual: Know your audience inside out and write in their lingo. Writing for a marketing audience is widely different from writing for an IT audience. Talk to them as an approachable guide, not as an uptight SME.

Tl; Dr: Keep the docs simple, short, easy to follow, exhaustive, and relevant to audiences’ needs.

3. Ask for feedback and iterate#

Writing documentation without feedback is like throwing darts but there's no dartboard. Darts are landing somewhere you don't know. Feedback helps in confirming your hypothesis whether users actually love your documentation.

If feedback is positive, keep doing the good work. If negative, you have valuable insights to make users happy. There's always room to iterate and improve!

Based on the feedback processes you follow, there could be qualitative or quantitative user input. You may have certain KPIs to hit. All of these will inform your decisions and help you in taking your docs to the next level.

Tl; Dr: Gather feedback from users and act on the feedback to improve user satisfaction.