How to Create API Documentation

Caution

This document is under development.

Best Practices for API Documentation

  • Create content that is easy to use, read and understand.
  • Make it easy to scan.
  • Include information about the architecture and why developers should use this API.
  • Make it easy to get started using the API.
  • Don’t leave out content (i.e., part of a command or a call).
  • Emphasize code samples.
  • Use meaningful, clear variable, class, and member names in sample code, even if they’re long. (NO FOO.)
  • Group functionality by function or method.
  • Make sure code samples are accurate.
  • Provide as many samples as possible.
  • Focus on tasks.

Sphinx has a lot of built-in tools for both generating API documentation from code and for documenting APIs.

See the Sphinx domains documentation for more information.

See the ASP Middleware API doc for an example of using the Sphinx javascript domain.

See also