I am researching documentation for api's. What makes a good documentation? What sections and articles are interesting for new and old users etc? Do you have any favorite documentation and why?
Thanks
Twilio, Stripe, Parse, Sendgrid, Mailgun are examples of companies with good documentation.<p>Generally, I like to see a high-level overview of the API, authentication scheme, endpoints, sample request and response, error code explanations, and sample code coverage in multiple languages. I wrote a blog post on this topic:<p><a href="http://murtza.org/creating-a-great-developer-experience/" rel="nofollow">http://murtza.org/creating-a-great-developer-experience/</a>
I like stripe-s documentation for their REST API<p><a href="https://stripe.com/docs/api" rel="nofollow">https://stripe.com/docs/api</a><p>curl examples are the thing that impress me the most ...
Take a look at beautiful docs[0]<p>[0] <a href="https://github.com/PharkMillups/beautiful-docs" rel="nofollow">https://github.com/PharkMillups/beautiful-docs</a>
New York Times Article Search API:
<a href="http://developer.nytimes.com/docs/read/article_search_api_v2" rel="nofollow">http://developer.nytimes.com/docs/read/article_search_api_v2</a><p>everything a dev might ever want to know about constructing a query, calling this API, and parsing the results--beautifully accessible from this homepage
I don't have a favorite company with good documentation, but these two tools have been useful and seem well designed for creating docs:
- <a href="http://daux.io" rel="nofollow">http://daux.io</a>
- <a href="http://raneto.com" rel="nofollow">http://raneto.com</a>
I second the vote for Twilio, adding NPR to the list
<a href="http://dev.npr.org/#story-lists-api" rel="nofollow">http://dev.npr.org/#story-lists-api</a>