What is useful in an external Web Service's documentation?

Question

I've just published a web service and written up some fairly primitive documentation. I've included the input parameters and output results, a short description of what each web service method does, and examples of possible errors.

What I've included in my documentation is pretty much what has been in the documentation of most web services I've consumed. I've taken a look at Twitter/Netflix/Amazon 's documentation and have some ideas I could use to improve mine but I think the Stackie community could offer some input.

• What kind of "features" make web service documentation a joy to use and help cut down on the support time a web service publisher has to spend dealing with misunderstandings?

• Are there any things you miss in web service documentation that you wish you had?

• What could make a web service's documentation invaluable?

I know its a lot of questions, but I'm trying to paint with a big brush to get as much feedback as I can.

Answer 1

Examples are what do it for me. My ideal doc has numerous, clearly labeled examples that illustrate the basic operation of the technology in question and hint at advanced features. They don't have to be absolutely exhaustive. Just enough to give me an idea of how the thing is used in useful situations. Beyond that, a clear and exhaustive description of what it does overall (with input, output, and methods explained) is ideal.

A good example of this is the doc for SQLAlchemy. It's split up into clear sections that delineate the toolkit's aspects and strengths. Within the sections themselves, the doc is littered with in-line code examples that walk you through basic operations and shed light on how you would take them further. I just started with SQLAlchemy yesterday and was able to write the script I was after in no time.

Answer 2

I would agree with Evan Meagher. One of the best things you can do is provide example applications that use your web service. You could write the world's greatest user documentation, but people would appreciate more being able to see example source code for themselves.