Recently I had a chance to work with one of the most honored developer experiences out there - with Stripe, https://stripe.com/docs
Here are a few things I really liked about the docs there and a few flaws I found.
But to be clear, overall I rate Stripe docs very high.
(+) First of all, it's awesome. Human readable prefixes in the API keys, omg, why does not everyone do it?!! I.e.
price_******for a price key and
sub_*******for a subscription key
(+) Docs are user story based, which is very cool. It's easy to go with the flow and find what you need. Would totally adapt that. Search is also good, but it is a must nowadays
(-) The subject area is huge, some specific things are hard to find though, i.e. subscription statuses are teased here and there, but the whole list is only in the API docs
(-) Some cherry picked dev docs/references are available through the main docs entry point, but others live at https://stripe.dev and there are no easily findable direct links to the server sdks from the main docs
(+) Server (at least Node.js I worked with) SKDs are exactly like the API reference. This is insanely convenient. I suspect this is one of the reason why the server SDKs are not featured in the main docs
What do you like and dislike about developer docs, for Stripe or any other product? Share some examples!