[HN Gopher] Ask HN: Best and Worst API Documentations?
___________________________________________________________________
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.
Author : shreythecray
Score : 17 points
Date : 2022-09-08 18:22 UTC (4 hours ago)
| and0 wrote:
| 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.
| kennydude wrote:
| 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!)
| MrWiffles wrote:
| 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.
| TheJoeMan wrote:
| 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
| bballer wrote:
| 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.
| and0 wrote:
| Stoplight looks great, but I'm wondering if there are any open
| source alternatives?
| username223 wrote:
| 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.
| PaulHoule wrote:
| 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.
| oxff wrote:
| Best: Github, MDN, Rust standard lib docs, Stripe.
|
| Worst: anything MS (excl. Github obv).
| thebradbain wrote:
| C# has some of the best first-party documentation of any
| language I've worked with
| spacechild1 wrote:
| What do you dislike about NS documentation? I always found it
| very thorough and useful. Definitely much better than Apple.
| shreythecray wrote:
| MS docs definitely make me want to cry sometimes
| wizofaus wrote:
| 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.
| superchroma wrote:
| 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.
| andywood wrote:
| 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.
| GOATS- wrote:
| Don't even get me started on Unreal's Python API docs.
| mikejulietbravo wrote:
| following this
| krnlpnc wrote:
| 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.
| shreythecray wrote:
| Didn't know this was a thing, and it sounds awful and
| inaccessible.
___________________________________________________________________
(page generated 2022-09-08 23:02 UTC)