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.