Ask HN: Best and Worst API Documentations?
Really trying to improve my company's docs and I am looking for some examples of what to do and what not to do. It's really tough gaging how helpful or easy your own docs are so it would help to compare them to what other developers prefer.
40 comments
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.
- 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.
Could you share an example of a code snippet that is meaningful vs one that isn't?
cryathefrayed, do you think this will help?
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.
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.
I would like to add: biggest things about code samples:
1) Use every parameter / return in the example. There is no good reason to put
(_, speed) = myFunc() because what is the first returned value?
2) Don't name the input parameters the exact same as the variables, even though it reads nicer Class Pet: func pet(pet)
pet=Dog Pet.pet(pet) <----- whyyyyyyyyy
2) Don't name the input parameters the exact same as the variables, even though it reads nicer Class Pet: func pet(pet)
pet=Dog Pet.pet(pet) <----- whyyyyyyyyy
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!)
* 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 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'm not as fond of the redesign that took place sometime in the last decade or so, but I remember the old (circa 2000) Win32 docs as good examples of great documentation.
For the worst ever in all of human history, I submit the official Unreal Engine docs. They never finished them, and they ain't gonna. If it didn't come with full source I'd never get anything done because I'm not about to sit through 100 hours of YouTube videos to find the details I need.
A lot of software relies on user-created documentation these days. And it's not even a decent wiki anymore. It's more likely to be YouTube and a Discord. Damn kids.
For the worst ever in all of human history, I submit the official Unreal Engine docs. They never finished them, and they ain't gonna. If it didn't come with full source I'd never get anything done because I'm not about to sit through 100 hours of YouTube videos to find the details I need.
A lot of software relies on user-created documentation these days. And it's not even a decent wiki anymore. It's more likely to be YouTube and a Discord. Damn kids.
Don't even get me started on Unreal's Python API docs.
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.
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.
Didn't know this was a thing, and it sounds awful and inaccessible.
Best: Github, MDN, Rust standard lib docs, Stripe.
Worst: anything MS (excl. Github obv).
Worst: anything MS (excl. Github obv).
C# has some of the best first-party documentation of any language I've worked with
subjective: I thought even Java had better docs than C#
What do you dislike about NS documentation? I always found it very thorough and useful. Definitely much better than Apple.
I've found Microsoft documentation (Azure services specifically) to be a weird mix of marketing and semi-technical walkthroughs that seem targeted to point-and-click users following their happy path. As soon as you get to the technical reference (if you can find it) it seems to all be auto-generated and fairly poor quality, or handwritten and either out of date or just not very clear.
The more "core" Azure services are a bit better, but it seems to always be a struggle and searching for answers is always difficult because you have to scroll through a full page or more of Microsoft marketing pages before you reach either Reddit or stack exchange results with the answers you're looking for.
Weird example: recently I discovered Azure redis instances will drop idle connections after 10 minutes, but the network connection still stays open and your commands/queries will fail.
The more "core" Azure services are a bit better, but it seems to always be a struggle and searching for answers is always difficult because you have to scroll through a full page or more of Microsoft marketing pages before you reach either Reddit or stack exchange results with the answers you're looking for.
Weird example: recently I discovered Azure redis instances will drop idle connections after 10 minutes, but the network connection still stays open and your commands/queries will fail.
I guess we just had completely different things in mind. I often need to consult the Win32 docs and I always found them very clear and extensive. Here's a random example: https://docs.microsoft.com/en-us/windows/win32/api/processth...
I think worst is an injury inducing stretch, but I'm not a fan of them personally.
This seems to be a problem with modern docs but I find they're overly verbose and the focus is hello world tutorials to show off shiny things & advertise Azure, the quality tends to drop off from there.
I think good documentation is something I want to have open on the side to answer questions like:
* What module did I need again?
* How do I do X?
* Does this tool let me do X?
I'm going to go straight to tailwind, MDN, GitHub etc. MS documentation I'm going to google first because I ain't got time to read through a half dozen long form articles that might give me an answer. ASP.net? probably, Azure anything? I'll leave more confused and thinking about AWS...
This seems to be a problem with modern docs but I find they're overly verbose and the focus is hello world tutorials to show off shiny things & advertise Azure, the quality tends to drop off from there.
I think good documentation is something I want to have open on the side to answer questions like:
* What module did I need again?
* How do I do X?
* Does this tool let me do X?
I'm going to go straight to tailwind, MDN, GitHub etc. MS documentation I'm going to google first because I ain't got time to read through a half dozen long form articles that might give me an answer. ASP.net? probably, Azure anything? I'll leave more confused and thinking about AWS...
MS docs definitely make me want to cry sometimes
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...
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.
Stoplight looks great, but I'm wondering if there are any open source alternatives?
+1 for anything open source or free.
openapi.tools has a list, however I havent found anything like Stoplight
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
Pretty and enjoyable. Do you mind sharing which tools you used for crafting it?
Thanks in advance.
Thanks in advance.
I used React, and Tailwind CSS
Here's an example of how we do API docs https://m3o.com/db/api
best: stripe
following this