Poynter.org just published my how-to piece on reading API documentation.
It’s directed at readers with little to no coding experience. I hope the intended audience finds it helpful. The example I used — looking up New York Times “Harry Potter” movie reviews — was a fun one, rather than something more serious, because doing fun things lowers the barrier to getting started.
Reading API documentation takes patience and tenacity. Even the most experienced developers I know will sometimes come across documentation so poor that they spend a lot of time guessing at how the API works. So don’t feel daunted. Practice instead.
I’ll post a couple follow-up exercises here on Ricochet, but get started now by heading over to the beginner’s guide for journalists who want to understand API documentation.
Update:
Thanks for all the retweets, comments and link pass-alongs. Keep them coming, and feel free to ask questions and suggest other tutorial topics in the space below.
Michal Migurski of Stamen sent me some thoughts about writing APIs based on my post, which makes me think there might be hope for the way API documentation will be written in the future.
In the meantime, if you’re responsible for writing API docs — or technical documentation of any sort — Jacob Kaplan-Moss’s “Writing Great Documentation” instructional series is mandatory reading.
Jacob’s name might sound familiar to you: he’s one of the co-founders of Django, a Web development framework created by journalists and developers as a tool for doing data-based journalism.
Photo: Sean Dreilinger/Flickr