What makes good API documentation? A tech consultant’s perspective.

Image is copyrighted to Geek & Poke under a CC License

Introduction: Setting the Scene

Before diving in, let’s set the record straight.

I don’t have all the answers when it comes to API documentation.

What I’ve got are opinions — shaped by my own experiences in the trenches and what’s also clicked with others that I’ve worked with. As a Technical Consultant at GBG, I specialize in API integrations for GreenID, Australia’s largest IDV platform, and have contributed to the development and growth of Basiq.io, a leader in Australia’s Open Banking landscape.

I’m proud to have collaborated with some fantastic teams on great products, each with their own documentation journey. But no matter how solid our work, there’s always room to grow and get better. The insights I share here are meant to spark dialogue, offer perspective, and, hopefully, contribute to the ever-evolving craft of creating great API documentation.

What makes a good API documentation?

So, what does it take to create some solid API documentation? From my standpoint, it boils down to three critical elements:

1. Simplicity
2. Comprehensiveness
3. Interactiveness

Now I’ve just dished out 3 major buzz words and and I can almost hear my inner consultant applauding. BUT, hold off on the eye-rolling at the consultant speak for a moment, as I truly believe these 3 words succinctly sum up the key to creating genuinely effective API documentation.

Notably, platforms that treat their documentation as a product in its own right really excel in this arena. A standout example in the FinTech scene is Plaid and Stripe, known for their exceptional docs that I believe really embody these three principles.

Take a look at Plaid’s blog post about their documentation journey — it’s clear they’re justifiably proud of their work.

Simplicity is Key

Clear, Concise, and only a little bit of Jargon

Great API documentation should and always be easy to digest and understand. That comes down to a couple points.

1. Findability and Readability is a good start.
It all starts with accessibility.
Effective Information architecture is crucial here in ensuring developers, product or business individuals can jump online, search up your documentation and have a relatively easy time finding what they need to know.

2.Clarity over Complexity (so we can actually understand what we’re reading)
Using simple words over technical jargon can make a big difference in how we read, absorb and understand things.

Now of course some jargon is needed here and there in order to properly convey a subject or topic. Technically even the acronym ‘API’ is considered jargon, but, it’s about striking the right balance.

Now according to Postman (everyone’s favourite API tool) and their 2023 State of API Report — 53% of respondents were non-developers, highlighting the need for clear and simple documentation that anyone can understand — not just super genius developers.

https://www.postman.com/state-of-api/who-works-with-apis/#who-works-with-apis

This statistic really pushed home the fact that not all super technical people need to use APIs and thus documentation does need to be clear and simple.

Comprehensiveness

Depth and detail. Ensure all bases are covered

Ever had that moment where you’re using an API, and suddenly, some unexpected behavior pops up?

You reach out for support and end up waiting 3–5 business days only to be told, “Oh, that’s expected behavior.” Frustrating, isn’t it?

That’s why comprehensive documentation is non-negotiable.

We 👏 need 👏 complete 👏 feature 👏 documentation. But, what does this mean in practice?

• Complete Coverage: Every function, parameter, configuration, and response needs to be documented. This thoroughness ensures that users aren’t left guessing about any aspect of the API or platform they’re trying to use. This includes both commonly used features and those more obscure ones.
• Anticipating the needs of users: Good documentation anticipates questions. It doesn’t just present facts — it should guide and educate. This might mean showing sequence diagrams, flow charts, FAQs as well as something a little more helpful which I’ll cover below.
• Error Handling and Troubleshooting: It’s crucial to detail what might go wrong and how to fix it. No one wants to come across a random errors when using an API and have no clue how to decipher their meanings, and how to troubleshoot. This preemptive approach empowers us users to solve problems independently, which not only and obviously reduces support overhead but also improves the experience.

Interactiveness

Engaging the user beyond just words

Let’s cut to the chase — no one wants to read a 50 page PDF and walls of text anymore. We crave immediate understanding and engagement. This is where interactivity becomes crucial, making it a non-negotiable feature in modern API documentation.

So, what’s the big deal about making your docs interactive?

• Hands-On Examples: We’re talking about examples that users can mess around with. Change up the request, poke around the response — it’s all about seeing the API in action. This isn’t just about showing — it’s about doing and understanding. Tools like having a Postman Collection or Swagger file, I don’t think should be treated as extras — I thoroughly enjoy when these are front and center and intertwine with the API documentation.
• Instant Gratification with Feedback: Throw in an API call and see what comes back immediately. It’s all about trying, failing, and succeeding fast. This quick feedback is key to getting a grip on what the API can and can’t do.
• Sample integrations and code examples: There’s just something wonderful about seeing API functionality in a fully operational app that really makes things click for me.
  It goes beyond basic examples. Seeing how the API creators envisioned its use can really speed up your own integration process. It’s like getting a peek into the minds of the experts and not trying to figure things out on your own.

Conclusion: The Bottom Line on API Docs

Alright, let’s wrap this up. Good API documentation isn’t just a bunch of text and it shouldn't be treated as such — it’s about crafting a user experience intuitive and just as important as the tech itself. Just for the sake of repeating myself:

• Simplicity because no one should need a Ph.D. to understand an API.
• Comprehensiveness because users should have all the info they need at their fingertips.
• Interactiveness because if your docs aren’t engaging, you’re doing it wrong.

Platforms need to lift their API docs to the level of their tech — making them not just pretty, but a delightful to use.