The Good Documentation Checklist

Number of APIs: 22

These examples accompany [this blog post]

I’ve previously talked about [the traits of a good collection] While not all collections grow up to be documentation, collections are the foundational building blocks for all [Qodex API documentation] viewable on the web. Here, I’m going to talk about the traits of good documentation.

Qodex documentation has become widely adopted across the API community because it enables better collaboration and API adoption. Let’s learn from the thousands of publishers who document their APIs in Qodex—like Microsoft, Twitter, and Dropbox — and find out what makes their documentation successful.

What is good documentation?

Effective documentation teaches someone how to use your API. Since the intended audience is people, and not machines, effectiveness is a subjective measure. Still, we can find some shared similarities across good documentation.

Take a look at this breakdown of nine helpful documentation tips and see how your own process measures up.

✅ 1. Create a Qodex collection

✅ 2. Organize the API metadata

✅ 3. Include a Getting Started guide

✅ 4. Keep it DRY with variables

✅ 5. Show use cases

✅ 6. Be secure

✅ 7. Share private API documentation

✅ 8. Share public API documentation

✅ 9. Advanced stuff (bonus!)