Why good documentation can get you more love than $1000

Anytime I am asked to find and implement some 3rd party service for a feature (e.g. A programmable messaging service like Twilio or AWS SNS), the first thing I find out about each potential candidate is "does their API have good documentation?" This is because bad documentation can be an absolute nightmare.

We all get it, writing good documentation usually sucks... a lot. But in the end, it is worth it and will make life so much easier. Not to mention, with today's tools, it is a lot easier than you might think.

Below are some examples, but feel free to skip to the awesome tips at the end.

The Bad Example

In some cases, it is actually easier to create a new feature from scratch, than to try and figure out the documentation or to get the service to work how you intended. A recent notable example of this for me would be using osTicket for storing client damage claim notes.

The great idea being, "with osTicket we will have an entire ticket system dedicated to supporting client damage claims". This wasn't my idea, but rather someone else's that I was being forced to deal with.

Their documentation is best described as "lackluster at best". There are many problems with this documentation, but I feel the main problems are:

• No table of contents or search bar, so no easy navigation
• No code examples for any programming languages (such as JS, PHP, Python, etc.)
• It's a wall of text in some areas or next to nothing in others.
• Only shows what successful requests look like and gives no hints of how errors should be handled
• This API only consists of 1 documented endpoint (the 1 other endpoint "documentation" tells you to go look at the PHP file)

In the end, osTicket stored our data for a couple of years, but we ultimately just created a single table to replace it entirely so that we wouldn't have to maintain osTicket anymore. As I said, we really just needed it to store the damage claim notes, and no one ever really used it as a ticket system.

The couple of hours we used to install, configure, & integrate osTicket, in the beginning, would have been better spent on other tasks, and we should have instead taken 30 minutes to create a single table.

The Good But Unrealistic Example

Twitter is a large company with a lot of spare resources, so of course, their documentation is great and boasts a ton of good features:

• Easy to navigate or search
• A good amount of examples and tutorials for many languages
• There is a lot of text, but it is easy to find what you are looking for without needing to read every detail.
• Great explanation of errors and what to expect
• Good/clean page design
• etc.

This documentation is intuitive, informative, & highly detailed which is what makes it both useful and good. Twitter has put a lot of time, money, and effort to make it this way.

The Realistic & Good Example (aka tips for making awesome API documentation)

Many large companies also publish their documentation on Postman's platform, (such as Twitter, Imgur, & DocuSign) even when they already have an in-house-built solution. This is because Postman is reasonably free* and makes it really easy for developers to test, integrate, document, & share their APIs.

Documenting with Postman solves a few bad documentation issues by default:

• Easy Navigation (Table of contents & search)
• A good amount of examples for many languages
• Good/clean page design

From that point, we can focus more on tips for making your documentation and API easier to understand:

• Be detailed but to the point - Most people just want to know what it does, not it's life story from conception.
• Point-out important endpoints - If an endpoint largely depends on another endpoint or set of endpoints, it likely is a good idea to mention them in your documentation.
• Organization is key - Separating things out into sections (aka folders) can make information easier to absorb. Additionally, this can make it easier to search for stuff.
• Use simple explanations - When trying to explain anything, pretend that this is only the second page in the documentation that the reader has read. Treat them as if they know a little, but not everything.
• Don't be afraid to make suggestions - Help them understand what some best practices are when working with your API when they are relevant, such as dealing with errors or odd behavior.
• Document common errors/problems - No need to be super detailed, just give an idea of what to expect and possibly some basic solutions where they are needed.

Conclusion

You can spend well over $1000 dollars on the right hardware, software, & education to help you become the best at your job, but if you never put in the extra effort, you will never be the best.

While writing documentation can suck, in the end, it is worth it because while it may not make you the developer of the year, good documentation can make you a real hero.

Cheers! 🍻