API Documentation comes in a variety of forms. You can find it in
pdfs, html, or even a Postman-collection that lets you play immediately. You can provide project examples, detailed blog posts, or video walk throughs.There are tradeoffs of each. Regardless of how you deliver the documentation, all documentation fall into one of three buckets:
The descriptive style is what we’re the most familiar with. It is the encyclopedic form of our docs that lists every parameter, defines every term, and shows every end point. It’s 100% factual without any bias or preferences and probably written by the engineering team or auto-generated. These docs are absolutely mandatory when you’re in the depths of an API trying to understand the specific parameters and endpoints you need to combine to solve your problem.
That said, these docs are incredibly boring.
Yes, they tell you how to use the API but they don’t tell you why you should care. They don’t have any color or opinion woven throughout them to make a case for or against any particular approach. Since this is targeted at the developers building on your API, that may be okay but here’s the problem: The API provider is probably the expert in the space and definitely the expert on their API. Therefore, they should give us tips and suggestions on how to be successful instead of hoping we figure it out.
The storytelling style is much less common but incredibly powerful because it speaks to the overarching problem in a relatable way. Outside of technology, we call these myths, legends, and parables and they’re a fast and easy way to express complex concepts quickly. When I say the Good Samaritan, mention Icarus, or talk about Crying Wolf, the vast majority of people will understand what I mean.
When we do this in our documentation, it gets beyond the technology and implementation details and we have the opportunity to speak to specific use cases and personalize it. That’s when people remember it. At an expert level, they should build from and have threads from our overall brand and strategy, but that’s another post. (No, literally it is another post. Read that next!)
But remember the Storytelling style has to supplement the Descriptive, it can’t stand on its own. We need both to get work done.
The prescriptive style is the middle ground where we get into “best practices” and “recommended approaches” but most people actively avoid this style. While I don’t have formal data to back this up, I suspect it’s because we don’t like being told how to do something, so we assume no one else wants to be told either. It’s even worse if we have to say “you’re doing it wrong” or we simply can’t support that team’s use case. It feels like the worst of all worlds!
That said, these docs are incredibly useful for one simple reason:
You are the expert on your API and maybe the industry as a whole.
This is your chance to show me you understand my problem and how to solve it. When I decide to
outsource some of my technology stack use an API, fundamentally I’m saying “you do X better, faster, cheaper, or easier than I can.” Now that I’ve deferred to you, show me good patterns and practices that let me move even faster. Show me different options and the tradeoffs that come with each. Show me how to be successful!
Further, when you show me A Right Way, your team benefits. If you have sales engineers or offer consulting, their lives become easier and more predictable. Your support team should see less screwy implementations they have to debug. And some portion of your customers will get the job done without you getting involved at all. That makes your sales team happy.
Caveat: I stay away from using the phrase “Best Practices” because design & implementation decisions vary wildly based on constraints, requirements, tools available, and skills of the team. If you say there is one correct way, you end up in awkward conversations if a customer, partner, etc can’t follow them to the letter. Be careful!
Which Documentation Style is Best?
Of the three approaches, each has its own time, place, and audience, therefore I think you should work to have all three.
Cheap answer, I know so I’ll explain:
The Storytelling style is great for that first pitch. When I hit your website and I’m not 100% sure what you do or why I should use it, tell me a short story. Convince me that you understand the space and you can help me. It works well for less technical audiences who just need to know “can you solve my problem?”
The Prescriptive style is great when I’m designing and building. Show me a good way to do things that won’t blow up my project or my bill later. Teach me so when I face a decision you don’t cover, I understand the tradeoffs.
The Descriptive style is great when I’m building, debugging, and scaling. Once I understand you can solve my problem and I’m not making any big mistakes, it’s time for detailed design, integration, and coding. I don’t need opinions, I need parameters.
As developers, we like to stay in the Descriptive, are hesitant to write anything Prescriptive, and actively avoid the icky marketing of Storytelling and this is a major mistake. Each style is useful and when used properly, they can drive adoption, growth, and make everyone more successful.
Disclosure: A few months ago, I wrote much of Okta’s Recommended Practices for API Access Management with the above mindset. But I didn’t just start writing and hit publish. The first draft went to sales engineers and others to give raw, honest feedback. A later draft went to trusted customers who were in the thick of these decisions and wanted guidance. The final draft went through our Docs team who turned it into a great, finished product. It’s dangerous to go alone.