Cover by Lorna Jane Mitchell

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

O'Reilly logo

Chapter 15. 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 either logging a support ticket, or just going away and using you 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. In the following sections we’ll 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, 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 the more detailed information. In general, it ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required