API Documentation: Where to Begin

I work at Twilio. Thanks for the kind words in the article.<p>It's important to actually watch people use your documentation, to see how effective it is. The OP linked to our HowTo section as a good example of focusing on use cases. In user tests the HowTo sections are one of the least effective sections of our documentation. Most of the howtos are only available in PHP or C#, and the way they are written now makes it difficult to translate that code into the language the user would rather use. They also put more focus on working code samples than on explaining the concepts - people really struggle with understanding what happens when they get a call or a text at their Twilio number. We're working on revamping our documentation to help make this stuff more clear.<p>So I'd be wary - the concept of code samples is good, but the devil is clearly in the details.

I have been trying to help with API Documentation as well (mostly because of my frustration as a user). My main focus currently though has been in helping you use the API of code as opposed to REST API's (because most people have languages wrappers).<p>Check it out: <a href="http://docmaps.io/" rel="nofollow">http://docmaps.io/</a>

Thanks for mentioning the Klout API docs (<a href="http://developer.klout.com" rel="nofollow">http://developer.klout.com</a>). They're a work in progress, but we lean heavily on Mashery's I/O Docs solution for self-documenting response and request formats. I continue to work on expanding out more detailed docs, but I generally feel strongly that API docs should be entertaining and tell a story. This aligns fairly well with how Dwolla (<a href="http://developers.dwolla.com/" rel="nofollow">http://developers.dwolla.com/</a>) aimed their portal at both business and developers.<p>As an aside, we use Swagger internally to manage and self-document here, and then I/O Docs on the third-party developer side. It's a nice separation of concerns.

I really like using iodocs by Mashery, it's pretty simple (put all of your API calls into a single JSON file) and it allows you to quickly do example calls with different query parameters that your users can test out right on the documentation. Klout uses it now too, I believe.<p><a href="http://dev.mashery.com/iodocs" rel="nofollow">http://dev.mashery.com/iodocs</a><p>It's also open source, which makes developer me happy. The only thing I wish they would update is allowing JSON to be sent in the request body, which there seems to be an open pull request for on GitHub:<p><a href="https://github.com/mashery/iodocs/" rel="nofollow">https://github.com/mashery/iodocs/</a>

3scale (<a href="http://www.3scale.net" rel="nofollow">http://www.3scale.net</a>) uses Swagger to do this out of the box on all of it's API portals. Swagger (see <a href="http://swagger.wordnik.com" rel="nofollow">http://swagger.wordnik.com</a>) gives you live docs but also tools to mark up the code to rip out the specs when you update code.

This is a very helpful guide.<p>I'd like to add a where <i></i>not<i></i> to begin: putting a big <i>Woah, Nerds Only!</i> warning at the top of your API docs (I'm looking at you, Mailchimp[0]).<p>[0]<a href="http://apidocs.mailchimp.com/" rel="nofollow">http://apidocs.mailchimp.com/</a>

Mashape auto-generates a nice documentation and 6 client libraries in PHP, Ruby, Python, Erlang, Java and Obj-C without writing a single line of code.<p>Example: <a href="http://mashape.com/lambda/face" rel="nofollow">http://mashape.com/lambda/face</a>

Our team has had a fair bit of success with a ruby library that generates API docs from our acceptance tests: <a href="https://github.com/zipmark/rspec_api_documentation" rel="nofollow">https://github.com/zipmark/rspec_api_documentation</a>