So You Need to Document an API?
summary
Advice: treat API docs as three deliverables—conceptual, tutorial, and reference—and prioritize an authentication tutorial because first-call friction kills adoption. Use Sphinx + Read the Docs to produce all three, use Slate or custom Markdown for compact reference, and expect to hack MadCap Flare with one endpoint per page plus table snippets and Pygments for code highlighting if stuck. Provide curl examples by default, require developer and support review, and prefer generated reference only if source descriptions are actually filled out.
AI-written summary · about
chapters (21)
- 0:00Intro
- 1:44About me quickly
- 2:38Agenda
- 3:17API Definition
- 5:52Reference Documentation
- 7:00Preamble
- 8:36Who are your users
- 11:00What does the API do
- 12:10Third set of questions
- 15:30Complete endpoint reference
- 15:57Concepts to cover
- 18:28API Call Format
- 18:58My Husband
- 20:04OAuth Explained
- 21:37API Reference
- 23:06Twilio API Reference
- 23:45Twilio API Response
- 24:18Production
- 25:24Sphinx
- 27:31Slate
- 28:41Flair
