Documentation standards/structure/style for Web services

Question

Can anyone recommend guidelines for high-level documentation of Web services?

This is the documentation that should allow someone with no knowledge about a particular Web service to come away with a basic understanding of its reason for being, its roadmap and examples of its usage.

Such documentation should fit onto two printed sides of A4/Letter paper and take someone less than 10 minutes to read.

Note that this is supplemental to the low-level API documentation that a developer would use to consume the interface.

Answer 1

I'm not sure I have guidelines, but I can show you an example of something that I found to be a good set of docs for a web services API.

http://www.flickr.com/services/api/

The Flickr API pages are set out in a very readable form. This page basically has:

• Links to overview pages
• Writeups of common scenarios (uploading photos in this instance)
• Info on tools to consume the API
• Detailed descriptions of each API method, grouped by activity

In particular, the pages that describe the common access paterns (uploading a photo, replacing a photos) are, for me, vital. They show a consumer of your API how to do the common things and how you expect people to use your API. That last point is important - you want to say "hey, we expect you to call us like this, using these methods, with this sort of error handling". Show your users some best-practice around API usage and you'll save yourself a whole load of support calls.