Happy Writers and Unhappy Customers

This could be a common situation when customers are consuming your documentation. You’ve produced good work in researching the product, creating a blueprint, applying the writing style, and getting comments from developers. Your JIRA tasks met sprint objectives and were done in time.

Why Could Customers be Unhappy?

Unhappy customers may not be because the content is poorly written or is accurate. It may be because they have had problems using the documentation.

But Your Documentation is on a Website!

Your documentation is available to all from a website. You’ve picked a documentation tool that has effective templates, is easy-to-use, and fits nicely with the technical requirements of the software (e.g. it is a jamstack solution that uses static site generators). No matter how well-implemented or attractive the documentation appears in its design, it still doesn’t help the needs of the consumer.

Customers Still Call Support

When customers have no time, they would rather call support than read through the content. Even if the content is rich and informative, it may not help in certain situations. They may try to call support even though the documentation is there. Moreover, your company may have dedicated support channels, and they know who to call.

Understanding the Customer Journey

Whether or not a customer reads the documentation, their journey starts when they arrive at your site. They should be able to make a decision from the home page as where to go next. Normally, this is through a search or via the navigation menus.

Short Form vs Long Form Content

Short-form content gives the customer a brief synopsis of the product or functionality, allowing them to understand the product and make decisions on what to read next.

Long form content is information in more detail, covering procedures, reference material, and further concepts.

Both forms of content go together. Users may stop after reading the short form content. That’s great if the short form text provides all the information they need. Or, they could venture further in to the long content.


Many users explore the documentation from a search. Therefore, ensuring that the pages are findable from their keyword combinations is key. If your site is implemented in MadCap Flare, you can configure search by setting up various search tags. But if your documentation site links to a provider like Algolia, setting up search is almost automatic.

Navigation Menus

There are many ways to design navigation menus. While a left-hand menu bar is common, there are documentation sites with additional navigation menus in the main pages. This design exists in the Spotify help centre and the Akash Network. An over-crowded left-hand menu bar alone can make a site hard to navigate.

Organising the Pages into a Logical Order

Once customers know where to go, organising the pages in a logical order is essential for completing their journey. Depending on how they use your content, there may not be a complete right or wrong answer. For example, one helpdesk team informed me that typical customers would be less likely to read conceptual content before doing the steps. This differed from my own learnings of the product, and the initial feedback that I received.

Defining Quality

Lastly, improving the documentation to help customers should be part of a definition of quality. In her presentation at Write the Docs Prague in 2016, Riona McNamara from Google explains that quality in technical documentation can be defined as either Functional Quality and Structural Quality (see As Good As It Gets: Why Better Trumps Best). Structural Quality focuses on the immediately tangible areas that make documentation quality, e.g., the way it is written and laid out. Functional Quality, on the other hand, is whether the documentation achieves what is supposed to do.

In short, you could consider these two definitions in your plan to improve the documentation and make customers happy.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s