News for hackers. Stuff that matters.
Re:API Documentation and the Communication Illusion by Animats on Wednesday May 11, 2016 @06:02PM (#11679703)
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

Re:API Documentation and the Communication Illusion by ktRolster on Wednesday May 11, 2016 @08:06PM (#11680402)
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.