Your users will come to your solution with a wide variety of experiences and knowledge. They’ll also enter the documentation on a specific page likely based on their initial query into Google. This isn’t a call to better leverage SEO in your API docs, nor is it one to dumb them down. Rather this is a call to take a step back and leverage some end-user experience feedback from a different perspective.

For the majority of my school courses we started on page 1 of chapter 1. There was a logic to the textbook that walked us through the learning. Lessons built on each other and it was expected that you understood chapters One though Four before starting in on chapter Five. Some text books would have chapters that clearly stated “If you are already familiar with <concept name> you can skip this section.” I can assure you that most of your users are not going to begin with “Getting Started” and go down a linear path where they read and understand every page before finally arriving at the listTransactions API page.

They often didn’t select your service. That decision was made by another department higher up. But their experience will impact how much usage your application gets, and also who much penetration you will get into the firms. To distill this last point down, usage = consumption, and consumption = revenue for most SaaS applications. And don’t forget that penetration = stickiness, from which stickiness = stable revenue.

One of the big goals of APIs is to create integrations that automate more processes and also increase the  value the application brings. The initial integrations will be built by Professional Services staff. The people on this team have lots of experience and this is all they do. When they came onboard at your firm, they tackled the API Documentation like a textbook. They needed to be aware of the deep details, and they will learn it fast because of the purposeful learning they’ll do as well as having their coworkers to reach out to with questions. So yes, besides stable revenue, your customer support costing is impacted by the quality of your API Documentation.

That gets you “in the door” so to speak. But later on other departments might want a specific piece of data or to tie your service directly into part of their processes. Or it might not be that Professional Services were involved with the onboarding. More and more SaaS platforms hope to be simple enough that the customer can onboard on their own. If they’ve got a complex use case, your documentation could have made the difference for if you got selected or if the money went to your competitor.

I’ll use some of my recent experiences to highlight the pitfalls. An organization I work with is frustrated by the reporting of an application they use. “Sure, I’ll look at the APIs and create a script for you!” I’ve worked with APIs for years, and used to post-process a lot of data when I was an IT Engineer. Should be a fun project. Famous last words . . .

I did a Google query for “<application name> api list transactions” and the page I needed was high in the search results.

The page loaded quickly and looked promising. Parameters were listed, the endpoint was clear. And then I hit it – a “date” field with no format specified anywhere on the page. ISO 8601? Unix timestamp? MM/DD/YYYY? A quick scan of the page turned up nothing. A search through the rest of the docs turned up nothing useful either. Twenty minutes later I had my answer buried in a community forum post from three years ago.

This is the core problem. The person who wrote that documentation knew the date format intuitively – they had been living with this API for months or years. It never occurred to them to write it down because it was obvious to them. But I was not them. I was a developer landing on a single page from a Google search result, trying to get one specific thing done.

This is what I mean when I say API guides are not textbooks. A textbook author assumes you started on page one. An API doc author needs to assume the opposite – that every page is potentially page one for someone. Each parameter, each endpoint, each code sample needs to carry enough context to be useful on its own.

A few patterns that make a real difference:

• Every parameter should show its type, its format, and an example value inline – not in an appendix. If a field accepts a date, show the exact format next to the field name, every time.
• Error codes should link directly to what caused them and how to fix them. A master error reference page that nobody can find is not documentation, it is filing.
• Code samples should run as written. Pseudocode with placeholders is better than nothing, but a working example that a developer can copy, paste, and modify is worth ten times more.
• Getting started should get someone to a working API call in under ten minutes. Save the conceptual deep-dive for later sections that developers can choose to read when they need them.

The goal is not comprehensive documentation. The goal is documentation that works for whoever just landed on a single page with a specific problem and twenty minutes to solve it. That might be a professional developer at a SaaS company, a data analyst who knows Python well enough to get things done, or someone from finance who taught themselves to script because they were tired of waiting for IT. Build for all of them – not by dumbing it down, but by making sure each page carries enough context to stand on its own regardless of who is reading it.

Hero photo by Mona Jain on Unsplash – modified by author. API images and non-linear path simulated using ChatGPT.