The inverted funnel of API documentation

Click the image to download the PowerPoint slides, or download the PDF

I just got back from API the Docs, Chicago, 2019, where I had the pleasure of hearing from some dedicated practitioners in the field of API documentation talk to about 100 equally dedicated practitioners about API documentation. While I was there, I gave this presentation. The video of the presentation isn’t available, yet, so I have included a link to the slide deck and posted my edited notes below.


It was great to see so many people who shared a passion for making their customers successful through documentation. One of the aspects of technical writing that continues to motivate me is knowing that what I do is going to help a customer achieve and deliver their success.

My presentation was the last of the conference and, after hearing a lot of stories about every level of API documentation, I wanted to wrap things up by returning to the perspective of our customers’ and their journeys with our products.

Most recently, the customer journey has been more than an academic exercise to me, because, for the past several years, I‘ve been developing an information system for limited-resource clinics in Honduras. (

It’s been an incredible journey and one that has put me squarely in the customer’s seat with respect to API documentation. I have had use a lot of software documentation to bring the project it together and this experience has brought into focus a lot of the research I’ve studied and conducted on API documentation over the years.

Throughout my journey with the piClinic Console, my students and I have been studying users and usage to develop and improve the system. In just a few months, we will install the systems for their first field tests in Honduran clinics and we’ll know in a few months how we did. At the end of this summer, we’ll know more about our users and our system and our journey will continue.

That’s my latest journey.

I can say with complete confidence that software documentation played a critical role in helping get my project to and, ultimately, across the finish line. But, each of your customers has their own journey, and everyone at the conference was there to make it a successful one!

API Docs and Customer Journeys

I think we all can agree, that API Docs help your customers navigate their journey. They certainly helped mine! So let’s look at how customers use API docs to navigate their journey, and see how we can help them out.

To do that, we’re going to look at some funnels and pyramids. Not those from the slides (fortunately).

The conversion funnel

For a new API, many of your customers’ journeys start at the top of a conversion funnel. In that, you try to attract as many as possible into the top, so that you can:

  1. Make them aware
  2. Get them interested
  3. Make them want it
  4. … and get them to take action

Buy it. Use it. Learn it. Whatever your success action is, your conversion funnel guides your site’s visitors to do it. You know your site’s succeeded when the visitors take action. Once you’ve “converted” a visitor to a customer, your API docs, help carry them on their journey to achieve their success. Hopefully.

Documentation’s inverted funnel

While the conversion funnel guides visitors to action, on the other side of conversion, the documentation “funnel” becomes inverted and looks like a pyramid. In that pyramid, you’ll find types of documentation such as:

  1. A landing page or portal to attract them—there’s usually only one
  2. Hello World app(s) to get them interested
  3. Tutorials to show how your product can solve their problem
  4. Reference content– which makes up the foundation of the pyramid

While your documentation helps guide your customers to success, where to they come out of your [upside-down] funnel? They could come out, that is finish, anywhere! This makes it hard to know where to focus or which path their journey will take.

To meet this challenge, your documentation needs a solid foundation to be ready for them to finish, wherever that happens. Because each customer has different needs, your reference content must be thorough and comprehensive in order to be there when it’s needed.

The customer’s perspective

While this is recent and personal to me, I’m not the first to notice the need for reference documentation. Your customers are telling you what they value, but it’s not always measured in dollars (or any of the currency in the photo). It’s measured in time and attention.

Let’s look at the foundation of the documentation pyramid, the Reference Topics, or, as I like to call them, the unsung heroes of API documentation.

Time is valuable

Where do customers spend their time in your docs?

Developers will take a quick peek at the landing page and then look for something more hands on. The further down the pyramid, the more time they spend.

Hard to believe? Not for me, especially after my recent journey. On my current project, I spent almost all of my time in the documentation reading reference topics. But, it’s not just me.

Ref topics and examples

In a recent study of developers, researchers found that the developers they observed spent about half of the development session in the documentation. Of the time in the documentation, the largest amount of time was spent in reference topics and more than half was spent in the reference topics and recipe (how-to) topics.

Ref topics make you smarter

Further, about 10 years ago, I learned that Reference topics can make your customers smarter! It turns out that reference topics are more than just a helpful place to spend your time in the documentation. When the documentation has what you need when you need it, the developer doesn’t need to remember it. This makes them smarter by having the information they need, when they need it.

Reference topics, help developers throughout their journey, but, their biggest value is realized by the customers when they carry the customer across the finish line and enable them to ship their app.

However, you must remember that your customers could be different. Actually, they are most likely different. These were small studies and your customers might not be like me or any of those who participated in these studies.

The bad news from this is that these studies might not apply to you, your API, or your customers. The good news, however, is that they are not that hard to replicate so you can find out for yourself.

Ref topics show you care

At the end of the day (or the customer’s journey), your reference topics show your customers how much you care about their success with your API. They show that you’ll be there ready to help when they are close to realizing their success, or not.

Takeaways from the talk

Here’s what you can take with you.

  • Know your customers’ journeys
  • Be where developers need you
  • Automate as much as possible
  • Track the analytics that matter

Know your customers’ journeys

Know how your customers will solve problems with your API. Remember, your customers are probably different from me or another products, and they grow and change over time. You’ll need to always be learning about them.

Be where they need you

So, instead of asking if the documentation helped them, what if you ask them about their experience and their journey instead of about your doc. Take an interest in their work and where they are when they visit your documentation so you can learn where they are when they need it.

Learn where they are coming from to meet them there. With that info, you can be where they need you with what they need! The more you know about their journey, the better you can help them along.

Automate as much as possible

Developers have a lot of tools and processes to reduce the friction in the development process.

Take advantage of that! Find ways to engage more closely with the API developers and ways to merge and share your processes. This is likely to be a learning experience for both of you, so embrace that!

But, don’t let automation be an excuse to abandon the human touch. Automation doesn’t mean robot content!

Developers are people, too

Write reference topics for people

  • Reference topics handle many use cases
  • Less is NOT more with reference topics
  • Err on the side of more, not less content

Count what counts

Choose your metrics carefully and deliberately. It’s certainly important to track conversions–your API can’t make anyone successful if no one is using it! But, have a clear picture of what success with the product looks like (and measure that).

Content metrics are not a one-size fits all situation.

Tracking individual pages can help identify problems, but not customer success (they don’t read the help when they’re successful!). Tracking pages can help you know that the pages that are being read a lot are those that should be read a lot and those that are not read much are those that shouldn’t be.

Reference topics are different when it comes to tracking use and modeling customer value. It’s better to think of them as multi-page topics, not individual topics. So, aggregate their usage data into logical groups. For example, by topic area or product.

In the end, and the reason we attended this conference is so that after today, you’ll leave ready to attract customers to your portal better and help get them to their destination.

I hope you enjoyed some photos from my customer’s journey.

Credits and links

Image Credits:

All photos in the slide deck were taken by and are copyrighted by the author, Bob Watson, except for:


  • Brandt, Joel, Philip J Guo, Joel Lewenstein, Mira Dontcheva, and Scott R Klemmer. 2009. Two Studies of Opportunistic Programming: Interleaving Web Foraging, Learning, and Writing Code. InProceedings of the SIGCHI Conference on Human Factors in Computing Systems. Pp. 1589–1598. ACM.
  • Meng, Michael, Stephanie Steinhardt, and Andreas Schubert. 2019. How Developers Use API Documentation: An Observation Study. Communication Design Quarterly.
  • piClinic Console,

Related blog posts (with more references)

Leave a Reply