One of the most important and easy ways to avoid frustrating API docs is to check them periodically to make sure nothing is out of date.

Last year I started using Amazon's Flexible Payment Service (FPS) and their docs were so out of date that they linked me to a PHP library that was over three years old and already deprecated. I spent weeks getting my billing system working and then as soon as it went live I got an email from Amazon telling me that I was using a deprecated library that was being phased out in the next few months.

I also had the same experience with Twilio, although luckily with them the old library didn't work at all so I didn't waste time developing with it.

Updating basic things like links to helper libraries can save your customers countless hours of headaches and frustration.

For this reason I would say you need to automate as much as possible. Maintaining quality documentation is expensive, and although much of it requires a human eye there should be plenty of opportunity for machie verification too.

For instance, code examples (snippets or sample projects) should be actually compiled and tested, automatically, every time the docs or the API itself changes. Think of it as CI for your documentation.

I'm sorry you ran into the issue with Twilio. I'm in the position now where I can find and fix all of these issues so hopefully you won't see that happen again. If you email me your shirt size and address, I'll try to make it up to you. jsheehan@twilio.com

Another great resource:

http://jacobian.org/writing/great-documentation/

Soundcloud's API docs are quite impressive esp. their use of apigee console to test things out in the browser: http://developers.soundcloud.com/docs/

There's also a startup dedicated to (startup) API docs :) http://turnapi.com/

This is just as crucial as building your API properly, IMHO. I should be able to piece together my API integration from a mixture of examples, good documentation of deep features and caveats, and intuiting API methods.

For example, this API method (comes from real docs) is far from RESTful and leaves me guessing; what's the path for POST-PUT-DELETE (note, when I looked in the docs, API paths for those methods were not named POST/PUT/DELETE like this one is named get...)?

    https://myapp.com/api/v2/USERNAME/KEY/xml/company/get

I won't rant about API design as some HN'ers have posted excellent articles on proper RESTful API design already.

Docs that are out of date (I loathe developers that don't keep API docs up-to-date), misspell in examples or have un-tested examples, or generally are confusing to navigate are ridiculously unfriendly.

In relationship to this post whats everyone thoughts on smart docs like Posterous has? aka Mashery I/O docs, Swagger?

It takes the API explorer model to the next level....and integrates with documentation.

You get up to date docs + API explorer + code stubs. Is this the future?

What tools are out there to generate an HTML doc of your api? I don't necessarily need it to parse my code, but I want to take the busy-work out of coding HTML.

A bit out of date but I have used rapi-doc in the past: https://github.com/sabman/rapi_doc for some of our internal API reference docs, for quickly reminding ourselves of the current state of our API's. It's for Ruby on Rails though, so if you are familiar with RoR, it will parse your controllers looking for API related comments for each controller action. Here's an example https://beta.spacialdb.com/apidoc/layers.html But I am sure there are better tools out there, I'd be keen to learn about them.

We used sphinx (http://sphinx.pocoo.org/). Uses reStructedText and you can pull in comments/samples directly from your code to help make sure everything's up to date.

It's in a very early stage (not production ready), but some colleagues and I have been working on a automated testing DSL built on top of RSpec that lets you generate API documentation from tests which validate the documentation is correct. It requires RSpec and a Rack-compatible service (incl. Rails). I think the idea has legs.

https://github.com/zipmark/rspec_api_documentation

I like ROBOdoc [1]. It's not well known enough IMO, but it has the huge advantage to work with about any language you can think of, which is a real boon for mixed codebases (for instance C + Python + HTML + Javascript or any other combination you can think of). Of course it can be used to generate HTML, PDF, man pages, POD or about anything else.

[1] http://www.xs4all.nl/~rfsber/Robo/

I so wholeheartedly agree. I was just thinking about writing about the decline and fall of documentation.

It seems to me that as open source software has risen, good documentation has declined. That is probably inevitable, but it doesn't make it good.

If you can wrap your mind around making your documentation every bit as elegant as your code, you'll win friends and score career points.

this is a good description of the individual concerns, but it's missing a really important consideration that most API designers seem to ignore: what's the ideal way (or ways) for someone to use your API? once you have some answers to that, you can start designing an onramp to your API that subtly guides developers towards the kinds of idioms that you want them to learn. it's not just a matter of following the right form in the right example, but overall organization--what concepts are introduced as being related, the kinds of examples you have at all, etc.

Are there any decent open source applications that I can launch to create pretty API docs?

I see that GitHub says their API is Open Source, but is that the actually contributing to the API examples, or the actual code?

I wanted to invest in Twilio after I saw the documentation.

I wanted to work there after I saw the docs. Now I work on the docs and libraries at Twilio :)

(Now I'm an investor in Twilio too :)

And don't forget to include a reference to day9.