Best and Worst API Documentations?

Im not a pro hacker, but I occasionally have to consume an API. My personal golden rules are

- be meaningful. listWidget(str name): Returns a Widget is useless to me. 90% of api docs i see are like this, its evident they've been auto-generated and no effort had been made. Code samples help but really they are second order answers to the fundamental questions users have: why should I consume this function? How do I consume it? What should I expect? How to detect problems? And, hardest of all, when should I use something else?

- include an overview block at the start of every api definition, to orient the reader. What does this API do? What are the most important objects and calls? What limits and rules does the reader feed to know? Write at a lower reading level than you normally use to capture newbies and non native speakers.

- Meaningful code samples are great, but dont kid yourself. If the sample is unrealistic, particularly if you are eliding a difficulty that the real world practictioner is guaranteed to face, you are cheating yourself and them. Address it.

- make navigation easy. breadcrumbs, scroll to top, cross refs etc.

I've never found api docs that hit all of these, by the way.

Not sure if it's quite what you're after, or if it's as good as it used to be, but php.net's documentation was PHENOMENAL back in the day when I was just getting started (~20 years ago).

Worst: My god, look at Apple. Where's the documentation on MacOS?!

EDIT: One thing I would suggest is to find a balance between skimmable documentation (nobody READS anymore, we don't have time or patience for that) and explanation (extracted structure/data types alone aren't nearly enough). Also, code samples! Code samples all the way! These are very helpful particularly for people that don't speak English as their native language. It's one thing to skim some English documentation and not quite "get it", but a code sample illustrating usage in a simple context can go much, much further.

Recently one of the worst I've seen is a property management system's API:

* Bugs in the implementation

* JSON looks like auto-translated XML without an XML

* Nothing about data types, values for an enum you could expect

On the flipside, Stripe's is one of the best. Although the only issue Ive seen is webhook signature code always uses their SDK which I don't always want to use, and webhooks can't be configured on a per-payment basis so if you have multiple systems on the same Stripe account, all of them get notified of everything (unlike other payment providers!)

I find myself consistently pleased with the quality and consistency of the MSDN documentation for C#. It usually has a nice example for just about everything that deserves one.

I used to like DotNetPerls because it made me pause and smile with its strange almost zen-like analogies, but now it's gotten a lot more formal, which makes me a little sad.

I really like https://getstream.io/ docs. For me, SDK support is important, as are examples and templates that I can play with & build off of. I also like the API usage dashboard that Stream supplies when you login. Which veers into the terriory of dev portal, but worth mentioning.

Also, in terms of tools for actually building documentation, I recommend looking at https://docusaurus.io/ for clean, customisable documentation.

What not to do: host “self documenting” API docs which are only accessible from an API endpoint themself and contain zero context or examples, only terse names and descriptions.

Best: Github, MDN, Rust standard lib docs, Stripe.

Worst: anything MS (excl. Github obv).

If you're actively trying to improve the docs then you're already in the camp of "what to do"! Most likely the biggest challenge will be ensuring and enabling cultural change so that the documentation is regularly kept up to date. And obviously use the right platform - searchability, linkability (not just at the page level), ease of access and maintenance, etc. will probably make more difference to how successful your documentation is than writing style or level of detail etc.

Personally the thing I find most useful - and that is hardest to write - is a complete and realistic example of an entire flow.

For example on a recent API that I documented this needed to include a complicated OAuth flow (involving Swedish BankID), creation of several orders, and only then listing the actual account details.

Ideally you'll have this as an explicit test case and hike appropriate excerpts directly into your documentation, ensuring that your example actually works even if the API changes! There's nothing more frustrating than minutely explicit demonstration code that doesn't reflect reality - and it's very common!

Edit: I love the way that Rust's documentation generator allows you to include code snippets that will cause the documentation generation to fail if the code doesn't work! https://doc.rust-lang.org/rustdoc/write-documentation/docume...

I've always found heartcombo/devise's wiki to be a really easy read. I recall it was very helpful without too much info when I was just getting started. https://github.com/heartcombo/devise/wiki/How-Tos.

The original Perl docs are some of the best, with a nice balance of motivating "here's how to accomplish what you want" examples, and comprehensive reference material. It has grown flabby in newer versions, but parts of the original material remain.

Use Open API and then something like https://stoplight.io/ and you will get first class API docs that automatically update with your spec changes.

Lifeway CMS documentation was catastrophic a few years back. It was beautiful and deceiving at first sight, undiscoverable, adhoc non-compete, unstructured, full with multiple ways of doing things of which may or may not work depending on minor version numbers, description detail and pure luck.

The absence of documentation can be considered a form of tech debt, and tech debt can be deadly. In addition to what you're endeavoring, you could ask yourself, what risks am I actually mitigating by back-filling missing or poorly written documentation? The answer should guide your decision making. Sometimes, it's just a case of too little, too late.

Stripe is my #1, but lately I've found it's a little to terse on how some edge cases might be handled, or the shape of the errors I might expect.

I like the Python docs and the Java docs. I don't like the Clojure docs or the documentation for Javascript. The trouble w/ Clojure is that it takes some effort to wrap your head around the functional way of doing things -- Hickey's book is a great supplement to the docs.

It's not an API, but I get frequent compliments for my project's docs: https://onlineornot.com/docs/welcome

Best for me: https://api-reference.checkout.com/#tag/Payments

Here's an example of how we do API docs https://m3o.com/db/api

best: stripe

following this