Peter Gruenbaum of
SDK Bridge shared an article in the company's November newsletter that resonated with some of the work I've been doing recently -- creating API documentation for the Mimeo Connect REST Print API.
The article is titled
A Coder's Guide to Writing API Documentation and appeared in MSDN Magazine.
Gruenbaum says that writing good API documentation requires the four components:
- Overview: Explaining what advantages developers have in using the platform, and in some cases, providing an architectural description of the platform.
- Getting started: Helping the developer get started, in the form of step-by-step tutorials or simpler walkthroughs.
- Sample code: Providing well-commented code samples that developers can build on.
- Reference material: Providing detailed information about each class, member, function or XML element.
I have been writing sample PHP code while authenticating and writing calls against every endpoint on the REST Print API this week.
I have five developers interested in integrating the API into their applications. So I have been working on and overview and a getting started guide to our API.
I have been keeping reference materials to each web service on a wiki as I play with and learn more about our API.
Seems like I already have a good start, and seeing Gruenbaum's list of what makes up good API documentation validates where I chose to start with our API documentation this week.
