Developing API Documentation

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.