Use cases and case studies are in the grey area between developer and sales documentation. Some would argue that they are not “real” documentation, and that they should not be included on a developer portal. However, as web APIs have become mainstream and strategic so did their documentation portals: the content must also address the less technical objectives of the non-developer stakeholders.

Use cases and case studies play two crucial roles on a developer portal:

  • They act as social proof for your API product (sales function),
  • They can be an introduction to more specific, implementation scenario documentation types.

As with other types of documentation, there is not always a clear distinction between use cases and case studies: labels (taxonomy), structure (layout) and content depth and tone diverge depending on the team that is responsible for their implementation.

I selected 18 companies for this research; in this post I’ll give an overview of how they displayed use cases and case studies: How do these documentation types help companies to tell their audiences a story? How do they guide users towards specific content? I’ll talk about benefits and best practices and include some guidelines to set up a strategy to decide if use cases and case studies might be a good option for your own site.

What is a use case and what is a case study? And what about customer stories?

Use cases

Use cases describe actions or steps, defining interactions between the user (persona) and the system to achieve a specific goal or result. Use cases tell users how to obtain that end result and often address a technical audience that wants to evaluate and understand a specific problem or solution.

PayPal’s use case subpages list goals, include a sample scenario and a section with solutions, links to the docs pages and a Call-To-Action button asking for feedback. [Screenshot October 2017]

Case studies

Case studies present a problem-solving process from the perspective of the product/service provider and customer company. They are less about showing how something actually works, and are indispensable when you want to introduce a solution to a broad audience.

Example of a Dropbox case study that focusses on the experiences of the customer company. Customer quotes accompany a description of the project’s challenge, solution and results.

Customer stories

Customer stories advocate and/or review a product or service through the words of an actual user or representative of the customer company.

The companies often listed customer reviews into customer stories or customers. I found 3 possible formats. Customer stories can refer to:

  • customer testimonials ( text and/or video interviews),
  • use cases/case studies that are written from the customer company’s perspective (spiced up with customer quotes),
  • articles written by authors from the client company.

The label Customers leads to customer testimonials (e.g. via video interviews) and case studies (Apigee)

Customers: guest authors provide use cases and case studies. The content varies: depending on the position of the writer the reader gets more technical details (DigitalOcean)

Alternative labeling

Companies sometimes prefer their own custom labels to illustrate product and service analysis. The reviewed sites used success stories, showcase and customer success mostly for case studies (as per definition above).

Instagram’s Success stories list case studies of customer companies. The subpages have a story - quotes - goals - solution outline.

Display of use cases and case studies

Primary focus: customer, problem, product, solution?

Several articles give general guidelines on how to display use cases and case studies (e.g. wikipedia has an extensive list of what you can include into use cases).

In practice, though, the companies in my sample lot often deviated from those theoretic blueprints and established their own set of rules.

The primary focus is usually similar. Most of the companies that listed “case studies” were customer oriented. “Use cases” mostly focused on product/solution (3), product/solution/customer (2) and solutions (2).

Chart: What do use cases and case studies primarily focus on? (based on the data provided by 18 companies)

Stripe use cases focus on product, benefits, solutions and customers.

We can make a light distinction between:

  • Customer and problem oriented scenarios (How did we solve a problem or provide a service to our client?)
  • Product and solution oriented scenarios (What can you achieve with our API product?)

Most companies use a variation of two structures to display information:

  1. Customer and problem oriented scenarios could have the following layout:

Some examples:

Case studies: challenge, solution, results on the left, the customer company info on the right (CenturyLink)

Case study on Keen IO’s site: customer company info on the left; graph, mission and solutions on the right. CTAs at the bottom of the page.

  1. Product and solution oriented scenarios could follow a layout like this:

Some examples:

Case study in PDF format with synopsis - situation - challenges - how Dwolla helped - features used - timeline structure (Dwolla)

An example of a Twilio use case: Goal, benefits, CTA to contact the sales team, links to a “build it” tutorial, fact checks about companies that used this product.

Search easily: select from categories

Some sites included filtering options like companies, types of industry, topics, featured cases, regions, product, goals, solutions.

Filtering options: Goal, industry, region and products used all link to case studies of customer companies (Pinterest)

Filtering options: Industries, solutions link to case studies of customer companies (Orange)

Role in user journeys

Case studies and use cases are API documentation types that can play a role in the user journeys of both decision makers and developers.

First, they can help new site visitors evaluate what the company’s API product is about by listing intriguing facts, showcasing features, sharing customer opinions, or celebrating interesting implementations.

Customers: interviews with customers, case studies with quotes, videos and articles by guest authors (Keen IO)

Second, they can help speed up the stakeholders’ user journeys in general, e.g. provide specific product details (like code snippets) or audience-focused links that lead to a content niche on site. Where these case studies are placed in the site's architecture (business site, developer portal, blog) reveals which user-objectives they primarily target.

Code snippets and links to GitHub in a case study on the Google developer portal.

Twitter use cases on the developer portal focus on solutions first and then list benefits, products, (customer oriented) case studies, tutorials and links to more detailed developer documentation sections.

Twilio provides a Not a Developer? page. The listed use cases try to lead the visitor towards more and more specific and thus personalized descriptions, with journeys that could either end on the “Talk to Sales” page or on the developer documentation pages.

Primary focus on customer experience, secondary focus on “goal - solution” descriptions for decision makers (Instagram case studies on business site)

Blogs are informal, unstructured communication tools that can engage current and future customers: use cases as a content category on the Adyen blog.


Use cases and case studies can help market your API:

  • They offer a perfect opportunity to introduce product benefits and illustrate specific solutions. The balance between “share knowledge, not features” also defines to what extent you are likely to attract developers.
  • They can feature the customers themselves and give, a unique insight into the whole process that goes with researching, evaluating, planning and implementing an API product.
  • They can recommend and celebrate the usage of specific API products, this can attract new users.
  • They are easily accessible: case studies and use cases are usually written in everyday English. Their structure provides an ideal environment for quick scanning. Infographics and icons aid comprehension.
  • They can shift the focus towards user specific content through subcomponents like step-by-step guidelines or descriptions, infographics, tables, code snippets, links to documentation pages, features.

Use case description with resources and guidelines (DigitalOcean)

Think ahead: combine your strategic decisions and industrial best practices

My research sample showed that use cases and case studies, but also customer stories are widely applied, but the companies that include them define their exact definitions, labels and use.

An example of overlap in word choice: use cases link to case studies on the Dwolla blog.

In order to be able to decide whether you would include use cases or case studies on your site to show expertise, I listed a few questions and added some best practices that can help you decide:

What role will the content play in the user journeys of your primary audience? How does that influence their place in the site architecture? What page structure, labels and subcomponents match your personas best?

Best practices: Focus on what your audience would expect to find: make the labels, their place in the site architecture and the specific subcomponents consistent, e.g.:

  • Add use cases (label) with code snippets and descriptions with features (subcomponents) on the developer portal (place in the site architecture), among other API documentation types.
  • Make customer stories (label) that advocate solutions (subcomponent: description with quotes) available on the business site (place in the site architecture).
  • Add CTAs or in-links to related or more detailed information elsewhere on site. Include visual design elements, like infographics, videos and icons.

How can you make sure your users will be able to evaluate the provided content quickly? How can you improve their user experience?

Best practices:

  • Write plain English, provide a clear structure and an easily accessible format.
  • Provide an overview page with filtering options.
  • Add descriptions of how you define use cases and case studies at your company.

This research

For this post, I derived data from the business and developer portal sites of 18 companies with different business profiles: Adyen (Adyen case studies, Adyen customers), Amazon (Amazon case studies, Amazon use cases category), Apigee (Apigee API management use cases, Apigee API management case studies, Apigee customers), CenturyLink (CenturyLink case studies, CenturyLink use cases category), DigitalOcean (DigitalOcean customers), Dropbox (Dropbox customers), Dwolla (Dwolla use cases), Facebook (Facebook success stories), Google (Google showcase), Instagram (Instagram success stories), Keen IO (Keen IO customers), Mapbox (Mapbox showcase), Orange (Orange customer stories), PayPal (original link no longer available), Pinterest (Pinterest success stories), Stripe (Stripe use cases category, Stripe customers), Twilio (Twilio use cases, Twilio showcase use cases, Twilio customers, Twilio Not a Developer page) and Twitter (Twitter case studies, Twitter use cases).

About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.