4 ms·
Ask HN: What makes a great API documentation in your opinion?
There are a lot of different ways to do documentation.
There are the basics like having good SDK/libraries references. For example, [Stripe's famous 3 panels view](https://stripe.com/docs/api) is one of many ways of displaying that information.
It does get quickly blurry when you introduce topics like:
- Explaining the main concepts of the products/API
- Quick Start Guides (multiple languages?)
- How-tos for the main use cases
- Tutorials such as how to do <use_case_x> with <specific_language_or_framework>. Do you even include that in the docs?
Then there are the features of docs:
- Button to try this function/API call
- Includes the user' API keys in the sample code if they are logged in
- all of the content in one very long page or split it up.
- etc
So HN, what do you like to see in an API documentation? from little features, cosmetics, layout or how to structure the content. I want to hear about it!
- kstirman 10y agoIn 2009 I was working on building out API docs and looked around for good examples. Stripe was so far ahead of everyone else. I still think they have some of the best documentation out there.
- alistproducer2 10y agoI like reference APIs mixed with examples. MSDN is great when it does this and pretty horrible when they don't. There's nothing worse than a highly composed API (think Android) without examples.