How to Write Documentation that Engineers Love

Many engineers struggle to write high quality engineering documentation. However, documentation is an important part of any products go-to-market plan and needs to be treated like the documentation is a product in itself. This is especially true for developer tools, where documentation is needed to fully understand how to use the tool.

In order to write documentation that engineers love, your documentation needs to have the following categories:

1. Product Overview
2. Getting Started Guide
3. Use Case Guides
4. Reference Material
5. Troubleshooting Guide

This top level categorization allows engineers to quickly find what they need and get back to work.

If you look at the Twilio SMS documentation as an example, you can see that it has a Product Overview page displayed upon opening the documentation as well as a Getting Started Guide, Usage Guides, an API Reference, and a Troubleshooting guide in the left hand navigation.

Product Overview

The Product Overview page serves to better educate your users on how your product works. More importantly, it can serve as a page that your users can point their coworkers to which helps drive adoption.

The Product Overview should explain what the product does and how it works. If the problem is hard to explain using words, there could be a technical explainer video or diagram to help illustrate what the product does.

It doesn't need to be long, just long enough so that your customers can conceptually understand what the product is.

Getting Started Guide

Also known as the Quick Start Guide, The Getting Started Guide is probably the most important section of your documentation. It is meant to be a bare minimum step-by-step guide on how to get some value out of the product.

The Getting Started Guide is the only thing that prevents new users from giving up when they get stuck trying out your product for the first time. It should be a step-by-step guide with super clear instructions so that it is impossible for a new user to mess up. At the end of the Getting Started Guide, the user should have accomplished something and feel motivated to try out the more advanced features of your product.

Is it important to have high quality screenshots and demo videos to help the user navigate where to click. Don't assume that users will know where you put your buttons or dropdown menus because this is probably the first time they have ever used your product.

Use Case Guides

Use Case Guides are step-by-step recipes for how to complete common tasks or workflows.

In addition to helping unblock users on common tasks, Use Case Guides also let your customers know what kind of things they can do with your product.

You don't need to list every possible workflow with your product in the Use Case Guides section. You can start with a few common tasks and then expand as people ask your customer support team questions. If a question gets asked enough, it may be worthwhile in investing in a Use Case Guide so you can link customers to it the next time they ask.

Troubleshooting Guide

The troubleshooting guide is the place your customers should go to when they get stuck or seen an error. This section should include your FAQ, explanations of error logs, as well as fixes to common issues. It should also explain where to contact support if they are unable to solve the problem using documentation.

Reference Material

The Reference Material section contains your API Reference, SDKs, and any glossaries about your product. Most companies documentation is entirely reference material and could benefit from having the other sections mentioned earlier in this article.

There should be an easy way to test out any APIs listed in the Reference Material section. Some companies have a terminal embedded in their documentation where you can test out live cURL requests that are automatically populated with API keys.

Summary

It is important that your documentation site is more than just an API reference. At the bare minimum have a Product Overview and a Getting Started Guide in addition to your Reference Material. Then slowly add some common FAQs in the Troubleshooting Guide and additional Use Case Guides as common questions are asked through customer support.