Why your product needs good documentation
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
Let’s say there’s you and a competitor. Your products are both good, but your competitor’s documentation is very detailed. On the other hand, your API library only has a few lines of markup on Github.
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
When I worked at Samsung, we found that a large percentage of enterprise customers considered the quality of technical documentation when making purchasing decisions.
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
When you already have detailed documentation on your website, customers can resolve many of their problems without having to submit a support ticket.
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.
By tracking documentation page traffic and interactions, you can see which APIs and features developers use the most, and potentially what problems they may have with it.
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
Every time you communicate with your customer, you have an opportunity to tell them something about your brand and products. Documentation is no different.
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
If you aren’t familiar with what good documentation looks like, here are some best practices:
- 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!