Basics of API Docs

All REST API docs are divided up into two basic parts: reference materials and guides. People may refer to these by different names, such as tutorials or how-to's. I'll explain below how I categorize them and the major difference between the two.

Reference Materials

Reference materials are the first thing you need when creating API documentation. These are absolutely non-negotiable. toolchain Similar to how a dictionary is necessary when learning a new language, your API is unusable without a reference section.

While it's always important to for the content in the reference material to have good grammar, spelling and punctuation the #1 most important part of reference materials is completeness.

Reference materials must include:

• Authentication information
• Base URL
• Endpoint reference
  • Endpoint paths
  • Required parameters
  • Optional parameters

Reference materials usually includes:

• Request examples
• Response examples

While a dictionary is essential to learning a new language, it's only going to get you so far—this is where guides come in.

All of this information should be stored in an OpenAPI (Swagger) Spec and can be stored with the source code, or in a separate repo. Once the information for each endpoint is complete you can use a SaaS tool to publish your docs. There's no shortage of options (both paid and open source) that you can choose from and it can be overwhelming to figure out which to choose.

My advice is to not spend too much time picking a tool. The great thing about the OpenAPI Spec is that if you decide to switch you can do so with a minimum amount of work.

(I'm planning on writing more about my favorite docs tools, so I'll link to that post once it's done.)

Guides

I lump all the supplementary material that really help an API reference be useful in a category of 'guides'. These are often called tutorials or How-To's, depending on the organization.

Regardless of the name, well-written supplementary information is critical for a good developer experience.

The most common supplementary materials are:

• Getting Started Guide
• Feature Guides
• Troubleshooting
• FAQ
• Support

Getting Started Guide

The best place to start when creating tutorials is with a getting started guide (quickstart.)

The main goal of a quickstart is to get a developer from zero to a (small) working product as easily as possible. This gives the user trust in your docs and in your product. A quickstart that isn't quick, or that is full of errors discourages users from continuing. A quickstart that is overly complicated might even be the reason a user who would have otherwise used your product moves on to a competitor.

Feature Guides

Development teams work hard on each new feature included in your product, but no feature is complete without instructions on to how to use it. Feature guides are the link between developers and users. They also serve as high-level marketing tools—interested shareholders can skim them and see whether your product meets their needs.

Troubleshooting, FAQ, and Support

These are usually the mark of fully-fleshed out docs. While the goal is for each guide to be completely user-friendly and accessible to developers of all skill-levels, users will inevitably run into problems.

A designated support team can help troubleshoot, but any question that gets asked more than a couple times the answer should be available online. This can be on a designated FAQ page, or even as a Stack Overflow Tag.

Summary

When you're just getting started writing your API docs it's easy to feel completely overwhelmed. Don't let it keep you from getting started. Every additional sliver of information (as long as it's accurate) will be extremely helpful to a new user. Start by building out your OpenAPI spec. Once that's complete, write a quickstart. Listen to your developer and find out what they're struggling with. Iterate. You won't start with perfect docs, but with consistent effort it can become amazing.