This STC 2008 session by Daniel Wroblewski of SAP Israel introduced writers to API documentation, and he offered this minimalist approach to structuring it:
- Introduction (1 page)
- Who needs this
- What can I do with this API (main use cases)
- How guide is organized
- Quick Tutorial (1-2 pages)
- “I want to see it working”
- How to install or reference
- Concepts (2-3 pages, more if needed)
- Reference
- List of all APIs (e.g., Document! X, Javadocs)
- Other lists (syntax, types of windows, packages …)
Common goals of API users:
- to get quick overviews
- to get up and running fast, to see it working
- to see all of the cool things the API makes possible
Resources for API writers:
- Discussion groups:
http://tech.groups.yahoo.com/group/svcstcapi
http://tech.groups.yahoo.com/group/APIWriters - Models: Sun Javadocs, Google AJAX APIs, eBAY web services, Microsoft Windows APIs