PHP Web Services

Chapter 13. Documentation

Raise your hand if you like writing documentation. Now raise your hand if you like discovering that the API you are to integrate against is well-documented and has examples of applications similar to what you need it for. These two are in direct conflict since very often, developers don’t enjoy writing documentation, and while they often don’t read it either, good documentation will ease the path of developers into using your service rather than logging a support ticket, or just leaving and using your competitors’ offerings.

Your API might be the best the world has ever seen, but without any supporting documentation, or with bad/inaccurate documentation, people won’t be able to use it. In fact, without considering great documentation as part of your project, one could argue that you may as well save yourself even more time and not build the API either!

There are many types of documentation, and a great web service probably needs a bit of all of them. The following sections will look at the various kinds of documentation that are useful to accompany a web service and give some suggestions of tools you can use to generate and maintain these.

Overview Documentation

This is the welcoming committee of your API; it gets people over the threshold and gives them confidence that they are about to have a good time. The overview documentation will set the tone of the API and provide some pointers for where to find more detailed information. In general, it shows the style ...