12 Documenting an API
This chapter covers
- Reference documentation
- User guides
- Implementer specifications
- Change logs
In previous chapters, you discovered that designing APIs requires more than just designing usable APIs doing the job. Indeed, we have to take care of the whole context surrounding the API when designing it. But this context goes beyond that of the API itself—its interface contract, its implementation, and how and by whom it is used. API designers have to participate in various aspects of API projects, and a very important one is documentation.
The best designs of even the simplest things need documentation. As shown in figure 12.1, everyday objects can come with various types of documentation to help users understand how to use them, as well as to help the people in charge of building those objects to actually build them.
Figure 12.1 Different types of documentation
Page 1 of the Alarm Clock User Manual shows an annotated figure of the alarm clock. Thanks to that, users know what the components of the user interface are and their roles, even if the device’s user-friendly design makes this fairly obvious. But this first page of documentation alone is not enough to operate the alarm clock. That’s why page 2 shows its various functions, such as how to set the alarm by using the Set Alarm and plus and minus buttons.