Let Cherryleaf write your API documentation
Having Cherryleaf’s technical communicators write your API documentation is a great way to free up your developers’ time. As a result, they can focus on what they do best. We can provide you with a technical communicator to work on or off site, depending on your preference.
Effective API documentation requires more than a list of endpoints
“PSD2 and open banking is all about APIs. And an API is almost impossible to use without documentation. This means your PSD2 strategy needs to include a strategy for creating and delivering up-to-date API documentation.”
Developers expect to be able to find the information they need to get things done.
This can include:
- Getting started guides and tutorials
- Conceptual and overview guides
- Troubleshooting guides
- API reference guides
- Authentication and authorisation guides
It can be hard to find the time to document your APIs. With your developers used to focusing on details, this can also lead to documentation that lacks the big picture perspective. The answer is to have a Cherryleaf API documentation writer on your team.
API documentation portals for developers
When writing REST API documentation, a lot of organisations use the API reference documentation that can be generated automatically from an API specification.
The downside of this approach is the automatically generated REST API reference documentation typically has its own look and feel, and navigation structure. To the user, it often looks like there are two separate sites. One contains the reference information. The other describes 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. As soon as a website’s look and feel changes, there’s a cognitive load on the reader. They need to assimilate what has changed. It’s like trying to complete a task with two manuals open at the same time.
Instead, you can create a site that has a cohesive set of documentation. This includes having REST API reference content automatically generated from the API specification. Whenever the REST API specification is updated, that content automatically updates itself. It also includes all other important information, in a comprehensive and coherent user experience. It can also enable you to include a site search, manage multiple versions, manage pro/lite products, re-use content, publish to PDF, manage localised content, manage synonyms, and avoid inserting scripts into pages that only the original creator understands.
- API documentation portal home page
- Swagger Petstore – test 1
- Swagger Petstore – test 2
- Stripe-style API documentation
- API PDF manual
“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. “
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.
1-1 networking and free advice for software companies
Contact us if you're a software company looking for advice on creating Help content. We'd be happy to help you avoid some of the common pitfalls.
As many people prefer to meet in central London, we hold London 1-1 meetings in the exclusive Members' Room of the British Museum. We also use the Engineering Hub at the Institution of Electronics and Technology, next to the Savoy Hotel, which has rooms for larger and/or more private meetings.
Contact us if you'd like to meet up.
Good API documentation builds developers’ confidence in your product, and poor documentation can be seen as a sign of a badly-maintained API.
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.