API Documentation: Where to Begin | Hacker News Reader

API Documentation: Where to Begin

braintreepayments.com

49 pointsdan_manges12 comments

I work at Twilio. Thanks for the kind words in the article.

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.

So I'd be wary - the concept of code samples is good, but the devil is clearly in the details.

Thanks for this reply. I will be taking on an API documentation project for my team so I was particularly interested in this article, and thought the How To sections were a great idea. In my case, I don't have to support multiple languages, so that won't be an issue, but the additional insight into explaining concepts is helpful.

I am actually usability testing our tutorials now, asking them to read and think aloud. It has been really helpful to see people charge off down the wrong alley if the wording is just slightly off. I've re-written the tutorials 4 times already as a result. Also because we are supporting all 7 programming languages, watching a .NET developer vs. a Ruby developer has brought up some fascinating differences of interpretation.

Do you have concerns about keeping your documentation in sync with your source? I find that when I'm working with examples that if they don't work I first assume that it is me or something in my configuration. The last thing I think of is that the docs are out of sync with the example.

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).

Check it out: http://docmaps.io/

Thanks for mentioning the Klout API docs (http://developer.klout.com). 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 (http://developers.dwolla.com/) aimed their portal at both business and developers.

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.

http://dev.mashery.com/iodocs

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:

https://github.com/mashery/iodocs/

I built Happy Docs a while back for documenting APIs. It's still a work in progress. It mostly gets used for internal projects, so there isn't a good public example yet that showcases all of the features, but it includes a query tool (a bit of a work in progress), several authroing/editing tools, collaboration, and a few different export formats.

http://happydocs.net

3scale (http://www.3scale.net) uses Swagger to do this out of the box on all of it's API portals. Swagger (see http://swagger.wordnik.com) 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.

I'd like to add a where not to begin: putting a big Woah, Nerds Only! warning at the top of your API docs (I'm looking at you, Mailchimp[0]).

[0]http://apidocs.mailchimp.com/

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.

Example: http://mashape.com/lambda/face

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

Reply on news.ycombinator.com