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.
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.
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.
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).
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).
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:
- Customer and problem oriented scenarios could have the following layout:
Some examples:
- Product and solution oriented scenarios could follow a layout like this:
Some examples:
Search easily: select from categories
Some sites included filtering options like companies, types of industry, topics, featured cases, regions, product, goals, solutions.
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.
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.
Benefits
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.
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.
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).
