8 ms·
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.
- oxff 4y agoBest: Github, MDN, Rust standard lib docs, Stripe. Worst: anything MS (excl. Github obv).
- thebradbain 4y agoC# has some of the best first-party documentation of any language I've worked with
- skribanto 4y agosubjective: I thought even Java had better docs than C#
- shreythecray 4y agoMS docs definitely make me want to cry sometimes
- spacechild1 4y agoWhat do you dislike about NS documentation? I always found it very thorough and useful. Definitely much better than Apple.
- mdtusz 4y agoI'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.
- spacechild1 4y agoI 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/processthreadsapi/nf-processthreadsapi-createthread https://docs.microsoft.com/en-us/windows/win32/api/processth...
- DimmieMan 4y agoI 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...
- superchroma 4y agoI 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.
- andywood 4y agoI'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.
- GOATS- 4y agoDon't even get me started on Unreal's Python API docs.
- mikejulietbravo 4y agofollowing this
- MrWiffles 4y agoNot 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.
- TheJoeMan 4y agoI 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
- PaulHoule 4y agoI 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.
- wizofaus 4y agoIf 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.
- username223 4y agoThe 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.
- krnlpnc 4y agoWhat 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.
- shreythecray 4y agoDidn't know this was a thing, and it sounds awful and inaccessible.
- kennydude 4y agoRecently 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!)
- bballer 4y agoUse Open API and then something like https://stoplight.io/ https://stoplight.io/ and you will get first class API docs that automatically update with your spec changes.
- and0 4y agoStoplight looks great, but I'm wondering if there are any open source alternatives?
- vladsanchez 4y ago+1 for anything open source or free.
- rocketpastsix 4y agoopenapi.tools has a list, however I havent found anything like Stoplight
- and0 4y agoStripe 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.
- da4id 4y agoI'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 https://github.com/heartcombo/devise/wiki/How-Tos.
- kjellsbells 4y agoIm 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.
- shreythecray 4y agoCould you share an example of a code snippet that is meaningful vs one that isn't?
- aintmeit 4y agocryathefrayed, do you think this will help?
- DrabitoTech 4y ago[dead]
- rozenmd 4y agoIt's not an API, but I get frequent compliments for my project's docs: https://onlineornot.com/docs/welcome https://onlineornot.com/docs/welcome
- vladsanchez 4y agoPretty and enjoyable. Do you mind sharing which tools you used for crafting it? Thanks in advance.
- rozenmd 4y agoI used React, and Tailwind CSS
- pajamasam 4y agoBest for me: https://api-reference.checkout.com/#tag/Payments https://api-reference.checkout.com/#tag/Payments
- dcminter 4y agoPersonally 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/documentation-tests.html https://doc.rust-lang.org/rustdoc/write-documentation/docume...
- asim 4y agoHere's an example of how we do API docs https://m3o.com/db/api https://m3o.com/db/api
- r1jsheth 4y agobest: stripe
- aintmeit 4y agoThe 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.
- ndimares 4y agoI really like https://getstream.io/ 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/ https://docusaurus.io/ for clean, customisable documentation.
- croo 4y agoLifeway 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.