
API Documentation and the Communication Illusion - wallflower
http://jamescooke.info/api-documentation-and-the-communication-illusion.html
======
zer00eyz
Hey guys lets write documentation first, it will be great and clear everything
up.

Isn't this how waterfall development was/is supposed to work.

~~~
clay_to_n
Based on organization structure, and your timing, there's a point where it's
necessary.

If you have separate teams designing the client and server, you'll eventually
get to a point where you need to agree on the messages passed.

------
tmwilder
You might find this project interesting:
[http://swagger.io](http://swagger.io)

We use it to document services by reflecting docs off of the implemented
service. Upside, no drift!

------
Animats
Of course you write the documentation first. Both provider and user need it so
they both talk to the same interface.

Here's an API document I wrote.[1] Comments?

[1]
[http://sitetruth.com/doc/sitetruthapi.html](http://sitetruth.com/doc/sitetruthapi.html)

~~~
ktRolster
_Here 's an API document I wrote.[1] Comments?_

You asked, so:

The organization can be better. Usually when I am looking at an API, the first
question I have is, "What is this API, what can I do with it?" There's one
sentence about that in the header, but it's not very clear. Then you jump
right into low-level protocol details. Your pictures are good, and help to
understand, but they come way late.

The broad organization should be something like: 1 "Here's what you can do
with this API" 2 "Here's how to use it" 3 "Here are the fine details" and
maybe (4 "Legal garbage")

Nice quote at the bottom.

------
jzd131
Check out [http://apifortress.com/](http://apifortress.com/) I believe they do
the exact testing your looking for.

~~~
jamescooke
Looks interesting! Thanks.

