Let Cherryleaf write your API documentation
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.”
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
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.
“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
1-1 networking and free advice for software companies
We can also invite you to the Engineering Hub at the Institution of Electronics and Technology, which is next to Waterloo Bridge. This also has rooms for larger and more formal 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.