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.
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:
(uploading photos in this instance)
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.