Free up your developers’ time from writing documentation
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.
Cherryleaf helps you provide documentation that gets people using your APIs
Surveys by GitHub, ProgrammableWeb and StackOverflow consistently show poor documentation is one of the top workplace gripes for developers. 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. So when developers are creating APIs themselves, they find it hard to create the quality of documentation that’s needed.
Nobody likes writing docs? We do!
We really do love writing documentation for clients. We know with good API documentation, you can build confidence that your product is useful and well maintained.
With Cherryleaf’s API documentation writers on your team, you can provide the clear information your users need and expect.
The complete set of documentation your audience expects
Developers want more than just endpoints
With REST APIs, many organisations provide the API reference documentation that can be generated automatically from an API specification.
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.
This can include:
- Getting started guides and tutorials
- Conceptual and overview guides
- Troubleshooting guides
- API reference guides
- Authentication and authorisation guides
With a complete set of documentation, developers are more likely to use your product. Not only that, they’re less likely to contact Support.
“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. “
Creating a developer documentation portal
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 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.
How it works
These are most common steps in an API documentation project:
- We agree the scope of the project
- This involves understanding your requirements, the product’s capabilities, and the audience.
- We agree the price for the work. The price will depend on the size and complexity of your product.
- We agree a project start date and the project begins
- Research and planning
- Understanding your product in detail
- Understanding your users’ needs
- Creating a detailed project plan
- Develop a prototype
- To confirm the completeness of the information design
- Technical acceptability
- To confirm the fitness for purpose
- Develop the first draft
- Review by a technical or subject matter expert (and ideally, a user representative) for completeness and technical accuracy
- Develop the second draft
- Review by a technical or subject matter expert
- Final draft – it’s ready for delivery
Providing API documentation writers
We can provide you with a technical communicator skilled in writing API documentation. They can work on or off site, depending on your preference.
Fitting in with your existing development workflow
Cherryleaf’s API documentation writers can become part of your development process. You could treat documentation as code, committing it to source control, and including it in the builds.
API documentation episodes from the Cherryleaf Podcast
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.