
Designing Great API Docs - jamesjyu
http://blog.parse.com/2012/01/11/designing-great-api-docs/
======
the_bear
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.

~~~
jsankey
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.

------
forsaken
Another great resource:

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

------
sabman
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/>

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

------
apievangelist
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?

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

~~~
sabman
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.

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

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

------
chrisacky
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?

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

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

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

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

