Close your eyes and picture API documentation. You probably imagined a reference guide … that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you’ll need them all to have a successful API.

The Five Sections You'll Meet In Good Docs:
‌‌🍽 Recipes and Examples
‌‌🗺 Topical Guides‌‌
📖 Reference Guides‌‌
💬 Support Forums‌‌
📣 Marketing Pages

Recipes and Examples

Use-case-focused tutorials with lots of examples that can be copied and pasted

‌‌If you’re anything like me, when you get to a documentation page you scroll down until you see a code snippet, copy and paste it, and tweak it until it does what you want.

When writing docs, embrace this! APIs are incredibly flexible, however there’s always a few really common use cases. Create a section in your docs for use-case-driven recipes, with prominent examples that can be copied and pasted.

APIs tend to be modeled after how computers think: PUT the card resource, POST a charge, DELETE a user. But humans think in use cases. When they use your API, especially at first, they have a simple goal in mind like, “send a text message,” or “get a list of the 10 most recent posts.”

Walk people through a use case and include a large number of code samples. Think of it like a written version of sitting down and explaining to someone how to use your API. They’re tutorials that take the user from start to finish and accomplish a task.

Topical Guides

Deeper dives into advanced topics about your API

Topical guides are your chance to make a deeper dive into conceptual areas of your API. This is also where you talk about things like the philosophy around your API. You want users who buy into your API design, rather than fight against it.

For example, let’s say your API has a sandbox mode. There may be a flag in the reference guides, but this is where you talk about how to enable it, when developers should be using it, best practices around it, and more.

There’s a lot of decisions when it comes to designing an API. This is where you clear up assumptions, and make sure everyone understands your API. Explain pagination, authorization, API keys, rate limits, models, structure, pricing, and more here.‌‌These are often the hardest to write. When you design an API everything is obvious to you, but that’s not necessarily true to people using it. Creating a narrative explaining your API is important to set expectations, and make sure people are successful.

Reference Guides

A comprehensive description of all the ins and outs of your API

Ah, reference guides. This is a detailed list of everything about your API: the endpoints, the parameters, the headers, etc.

Reference guides are a bit of a paradox. They’re both the most AND least important part of your documentation.

Sure, it’s important–it’s where you detail all the endpoints. You get into the nitty gritty about all the parameters and expected responses. Users can’t see your code, so it’s important you’re extra explicit here about every little detail.

However, it’s tempting sometimes to make those your ONLY docs. They’re called reference documentation for a reason: they should be used for reference. You wouldn’t hand someone a thesaurus and expect them to learn English; in the same way you shouldn’t hand someone reference guides and expect them to learn how to use your API. Most of the heavy lifting should be done elsewhere in the documentation.

So back to that paradox about reference guides. They should be damn good. Anything wrong, and the person using them will be lost. But, if you’re doing your documentation correctly, most users should never have to use them.

Support Forums

Unstructured edge cases your users run into‌

Public support forums are the Wild West of API documentation. Your regular documentation should be written like a story, and kept tight. Nobody wants to read through every weird edge case and potential pitfall. Support is your chance to have unorganized content.

Now, support forums only work if they’re paired with a good search feature, or maybe a recommendation system at the end of a support article. However, they’re your chance to cram in a ton of random content that people will find useful. Make sure they’re public! Way too many people want to disable their public forums. For every user who actually wants to contact support, there’s a bunch of others with the same problem who will just move on instead.

Marketing Pages

Convince people about why they should be investing in your API‌‌

Before anyone uses your API, you need to sell them on it. All too often, APIs are coy on the details. You’re convincing someone to invest in you, so you should treat your API's marketing page the same way you’d treat any other. If a company is going to seriously invest in your platform, likely the decision won’t be made by a single developer. Rather, a team of technical and non-technical people will decide. And hey, even if it is one random dev, you still want to put your best foot forward. People do judge an API by its cover, and much like you’d sour on a website with a bad marketing homepage, you’d feel the same about APIs. There isn’t much specific advice for this, because every API is different. But as long as you think of your API users as, well, users, you won’t go wrong. Pay a designer! Hire a copywriter! You’ve spent hours documenting how you return error messages, but it’s all moot if nobody makes a call.

Things that don’t seem like documentation

When you say the word “documentation,” people picture paragraphs of text. Everyone here has a mental image of what documentation looks like. For me, though, I have an incredibly loose definition. I consider anything that helps you understand an API and get what you need to get done to be “documentation.”‌‌

• Error messages: They aren’t just for computers. Error messages a great way to convey information when something goes wrong. Nobody proactively reads docs about error codes; they only care once they hit it. Rather than making them Google for it and track it down, you can use error messages to surface documentation. When you return a certain error message, always include a link to the docs with it. If you want to take it a step further, you can include variables, so when the user clicks it, they see documentation filled with their actual variables.
• Change logs + status site: Is the API down, or did you just mess up? Did something change on your end or theirs? Don’t make your users crawl through a ton of debugging if the problem is your API! Make sure you keep a solid log of everything that’s changed and broken with your API, so your users don’t have to figure it out for themselves.
• SDKs: There’s a lot of debate about API SDKs. Purists think they add a bunch of unnecessary cruft on top of something that’s already perfectly language-agnostic. However, SDKs are great for smoothing out edge cases. Should the content be passed as form data or body params? Should it be encoded in a certain way, or have certain headers? Should the API key be a header, parameter, basic auth. … who cares? An SDK abstracts away all the tiny inconsistencies and details. Rather than forcing your users to read through nuanced paragraphs of text explaining all the little details, a good SDK can cut down on a ton of documentation.
• Integrations: When people decide to use your API, they likely aren’t doing it because they want to write code. Rather, it’s the best solution to their problem. Sometimes, I feel like we become too gatekeeper-y about our APIs. The goal shouldn’t be to restrict access only to people with computer science degrees, but rather to enable anyone to accomplish their goal. Maybe that’s done through Node or Python. Or maybe, that’s through a Zapier recipe or a Slack integration.

‌‌This post, and ReadMe in general, were heavily inspired by Jacob Kaplan-Moss’ 2009 article, “What to Write.”