Why your product needs good documentation

You need a docs stack as much as a tech stack.

Most developers nowadays are lazy. Why set up React yourself when you can just use create-react-app?

The same goes for the adoption of software products and API libraries. When developers use your software or API library, they want to know exactly how to use it and what to expect from it.

For that reason, your product needs good documentation. Many people dismiss documentation as unimportant, but you may be surprised to find that it can actually improve your bottom line.

Here’s five reasons why you should invest in creating good product documentation, or hire someone to do it:

1. Developers prefer products with good documentation

Unless your product is much better than your competitor’s, developers will generally prefer the one with better documentation. There’s a few reasons for this:

  • It allows them to use and integrate the product more easily
  • It reduces development time
  • It helps troubleshooting

It’s a similar reason why people tend to select tech stacks with well-known libraries like React and Node: there’s a big community around them, meaning there’s plenty of documentation online.

2. It increases sales

Good documentation not only helps customers to understand the product in more detail, but also allows them to estimate the development overhead required if they purchase it. This is especially important in enterprise software, which often requires heavy efforts in systems integration and testing.

In other words, your docs are as much a pre-sales document as they are a customer support document.

3. It reduces customer support tickets

This reduces the number of customer support tickets you receive, and means only the most important tickets will be submitted to your customer support team.

For enterprise, the average customer support ticket costs ~$100 to resolve. Multiply this by the number of tickets you currently receive that can be resolved through better documentation, and you can quantify the benefit of documentation as a customer support tool.

4. You can measure product usage.

You can also create feedback forms and rating scales on documentation to create a direct line of communication from the customer to you.

By having documentation, you create a way for you to collect metrics that can then improve product development or customer engagement.

5. Documentation allows you to engage more with your customer

Through your documentation, you can showcase:

  • How well you understand how the customer is going to use your product
  • Your commitment to helping the customer use the product
  • Why your products are better than competitors
  • How well you understand your own product
  • Other products that might help the customer

Lastly: the State of the Art of Documentation

  • Mention specific use cases for a product, and create tutorials or sample apps for the most common use cases
  • Write tutorials in a step-by-step way, with adequate detail in every step. Paste sample code or pictures for reference.
  • Write about common errors and how to troubleshoot them
  • For API references, use Swagger combined with ReDoc (or your own custom skin)
  • To create good API references, write detailed API descriptions.
    Good: vendorId is a 7 digit string that identifies the vendor, found on the user dashboard
    Bad: vendorId is a string
  • Have feedback forms or ratings scales on pages so that customers can rate your documentation
  • Apply good SEO practices to help your product and its documentation get discovered

If there’s one thing you take away from this post, just remember that product documentation can help the bottom line.

Feel free to reach out if you have any questions!

Agtech startup founder. Climatepunk.