Standards for API documentation
konklone opened this issue · 8 comments
I'm not inclined to recommend specific "solutions" for API documentation. Tools like Swagger, Apiary, and Iodocs all provide helpful accompaniments, but all are not great at being the sole documentation for an API.
Instead, I'd like to emphasize the goals that API documentation should have, and link to examples of other APIs embodying good practices of different kinds.
Goals of good API documentation:
- High-level "This is what the API is, what you can do with it, how our URLs/responses are designed" introduction.
- A quick-start or "hello world" tutorial.
- Real, syntax-highlighted example responses, next to the URLs that generated them.
- The documentation can be improved by users, e.g. is itself versioned in GitHub.
- Explanations of each field, and what promises that field is making. (e.g. possible enumerated values, whether it can be null, what type of data, an example value).
- Are clearly written, in professional language, without typos and grammatical errors.
Not all of these are deal-breakers — and clarity is ultimately a higher priority than 100.0% precision — but all contribute to solid documentation.
should of course be html, never pdf or word files
Be sure to give access to endpoint as quickly as possible
ensure plain language
I once saw API docs that had editable code right in the browser, which it would submit via AJAX. It showed the response in a separate part of the page. It was pretty amazing to watch people unfamiliar with APIs interact with this -- they started to pick it up right away.
Granted, this isn't always feasible. But I like the concept. I wish I could remember whose docs this was (I thought it was Twilio, but now that I look, it's not them).
That said, I think @konklone is right that you discuss the goals of API documentation, not specific standards.
Although Gray's point of "always HTML" gets a big 👍 from me.
I'd like to request "Examples" to the list of recommended documentation goals. Good examples can go a long way to explaining how to use an API endpoint and what the limitations are. Additionally, they provide a very easy copy/paste code to get someone to start playing with the API.