Give developers the API documentation they need and expect
Having Cherryleaf’s technical communicators write your API documentation is a great way to reduce your developers workload. They can focus on what they do best.
We help API providers get more people to use their API
Fixing your developer portal is one of the most effective ways to make your API successful. Documentation is the first place most developers go to try out or learn about a new API. It’s also the place they go to when they come across an issue with a program or platform they already know.
The problem is, writing documentation doesn’t always feel like a priority when you also need to code. Surveys by GitHub, ProgrammableWeb and StackOverflow consistently show poor documentation is one of the top workplace gripes for developers. This means many organisations find it hard to create the quality documentation that developers need and expect.
Here are nine typical Use Cases
- You’ve been providing APIs to your largest customers, together with a lot of onboarding and technical support. You want to have more (smaller-sized) companies use the APIs, but you’re worried about the strain that will place on your Support team.
- You’re releasing a new version of your API. The current documentation needs updating, but you just don’t have the time (or the technical communication skills) to do it.
- You’ve released your API, but its poor documentation means not enough developers are using it, you’re getting too many Support calls, or it’s seen as worse than your competition’s products.
- Your product offerings and APIs are going to get a lot more complex. You know you’ll need great content to explain what the APIs do, how to get started, and how to use them effectively.
- You’re launching your first API, and you know you’ll need to provide a great developer onboarding experience for you to succeed.
- Your developer portal/developer experience is a mess. There’s a lot of content, but it’s spread over explanations on Jira, readme files, files in a shared folder on Google Drive, PDFs originally developed for a single customer, web pages, wikis, video walkthroughs etc.
- Your developers are too close to the APIs and products to explain it fully in a way that a new user would understand.
- You’re getting battered by the competition, and one of the main reasons for this is that their developer documentation is so much better than yours.
- You want to develop an effective DevRel strategy, and, as part of that, you need to be able to create tutorials and up-to-date documentation at the times you need it.
Cherryleaf's technical writing services solve the API documentation challenges
With Cherryleaf’s API documentation writers onboard, you can provide the clear information your users need and expect.
We really do love writing documentation for clients. We know with good API documentation, you can build confidence that your product is useful, understandable, and well maintained.
What is your developer portal's KPI score?
Take this two-minute quiz to find out how your developer portal scores against key KPIs.
On top of that, we’re going to give you our top three tips for developer portal success!
How to create an award-winning developer portal
Case Studies
Creating a developer documentation portal for a financial organisation
An organisation in the financial sector had developed a collection of APIs and tools for accessing, integrating, and securely sharing data. They had provided some documentation, but it was contained in a number of PDFs and other formats that were hard to read and navigate.
They required a developer documentation web portal that provided overview and guidance, API reference documentation, and onboarding information.
Cherryleaf created an information design model of the revised website, and a complete set of redrafted and consolidated content. The content was organised in a way that follows the journey a developer was likely to take:
- Understand the product and services
- Setup the product and services
- Use the product and services to create apps, call an API, publish APIs, etc
- Look up reference information when developing
- Sustain/Resolve any problems
We reduced the amount of content, compared to what existed before, so the information was delivered in a clear and accessible way.
Creating API documentation for HCC Embedded
“The first, laborious, step was to get all the information organized into documents in a structured and modular way. As we complete the process we will want to improve presentational aspects to give a better customer and marketing experience.
We see an ongoing role for Cherryleaf as consultants who can help to get better documents out of the vast material we have added to the system. Very importantly, Cherryleaf were able to rapidly respond to our issues with the system and help us understand. We have no expertise in this and did not want to be stuck on things that experts could solve instantly – Cherryleaf were very responsive in this. “
See: Helping HCC deal with the size and complexity of embedded systems documentation
Creating API documentation for a well-known, international company
A large, international, multi-billion dollar company, had developed a series of APIs to make it easier for organisations to use its services. It wanted to provide a developer web portal that encouraged customers and partners to use these APIs.
Cherryleaf organised the content in a way that followed the customer journey:
- Discover the APIs
- Explain what the APIs do
- Explain the benefits of using the APIs
- Register to use the APIs
- Get subscription keys
- Use the APIs
- Understand the endpoints and code samples
- Try out the API sandbox
- Start their integration with the live system
- Sustain/Resolve any problems
We wrote a range of marketing, technical, training, and troubleshooting content. The project involved working with their API technical partner, product managers, and technical staff. The portal launch was very successful, with great feedback from the client.
Improving a developer portal for a large European financial organisation
A large European financial organisation had developed a developer portal containing APIs that developers could use in their own applications.
Often, developers needed to use more than one API in order to integrate a service. The organisation needed to improve the developer portal so that developers could understand how to integrate the products. This included:
- Providing a better onboarding experience.
- Communicating the relationships between the APIs (what they do, and how they work).
- Helping developers understand what an implemented solution would look like, before they committed to a production version.
- Stating any prerequisites.
- Providing information that enabled developers to use the products and APIs.
- Having consistency across all of the content.
Cherryleaf reviewed the site using a friction log to identify and record all the usability issues in the developer journey. We then developed an improved logical structure for the content in order to meet the needs of the audience. We also identified where content was missing, and improved the content on the website.
Google’s recommendations for developer documentation
With REST APIs, you can provide API reference documentation that’s generated automatically from an API specification file.
But API consumers expect more than that.
They want to be able to find the information they need to get things done. Even more experienced developers want to know what the API does, why you’d use it, how to get started, how to get an authentication key, how to get a “Hello World” response, tutorials, and so on.
Without that information, there’s a good chance they’ll give up, and move on to an API that does give them that breadth of information.
With a complete set of documentation, developers are more likely to use your product. Not only that, they’re less likely to contact Support.
For example, here’s the documentation Google recommends its developers provide for “curious beginner users”:
| Documentation Type | Description |
|---|---|
| Conceptual | Builds a deeper understanding of the underlying technology. |
| Cookbook | Explains how to accomplish a specific task. |
| API reference | Details all the elements in an API. |
| Getting started | Pushes a curious reader through the first few minutes of use. |
| Tutorial/Colab | Converts a reader from curious investigator to active user. |
| One-pager | Encapsulates the essence of a technology onto a single page. |
| Case study | Shows how users successfully employed this technology in the real world. |
This is the documentation that Google recommends its developers provide for “active users”:
| Documentation Type | Description |
|---|---|
| API Guide | Contains far greater detail (including edge cases) than a tutorial or Codelab. |
| Cheat sheet | Provides a condensed set of formulas, short cuts, or other hard to remember items. |
| FAQ | Answers individual questions that users ask. |
| Release notes | Details recent changes to a product and known problems. |
| Conceptual | Builds a deeper understanding of the underlying technology. |
| Cookbook | Explains how to accomplish a specific task. |
| API reference | Details all the elements in an API. |
That’s a lot of work for a developer to do.
Other ways we can help you
If you want to recruit an in-house technical writer
We can provide you with a technical communicator skilled in writing API documentation. They can work on or off site, depending on your preference.
If you want to improve your developers’ writing skills
We offer virtual classroom training courses in technical writing for developers:
- With Google’s courseware.
- With Cherryleaf’s courseware.
See Technical writing for developers: Virtual classroom courses
Contact us
Need help in developing your API documentation? Complete the contact form below. Don’t worry if you don’t know the answers to all of the questions.
We will contact you to discuss your situation and requirements.
You can always phone or email us, if you prefer.
* Required