STC2008 notes: Writing API documentation

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: