

API Documentation: Where to Begin - dan_manges
https://www.braintreepayments.com/blog/api-where-to-begin

======
kevinburke
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.

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

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

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

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

~~~
kellishaver
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>

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

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

------
sinzone
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>

------
d4mi3n
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>

