Print of the Yuno’s API Documentation developed by the Write Choice’s specialists
When working on a new feature for your software or API, you dive headfirst into the project. As a result, you know everything and are used to every jargon. However, have you considered how your users will feel when they get face-to-face with your API Documentation?
When you start planning and writing the documentation, and you have followed the entire development, every step looks easy, right? You feel you can jump directly to the application, leaving behind the basic configuration since it’s a walk in the park. However, when you present the final documentation to your customers, they get completely lost. They ask for support because they don’t know where to start and the steps to follow.
Was this scenario relatable enough? Well, most of the available API Documentation on the web faces the same problems: they don’t know whom they’re writing to and don’t know how to structure the information to serve the customer better.
But if you want to have excellent documentation for your product, this article is what you need now. We will guide you through the potential challenges you may face, the best practices to structure your API Documentation, and one example of a marvelous documentation to get inspired.
The first steps towards structuring or perfecting your first API Documentation can be similar to walking blindfolded. You know you can do better, but you don’t know how to diagnose what is going wrong.
We have listed some primary issues you may encounter throughout this journey. Doing so will help you understand the problems faster and how to address them accurately.
When you have lousy API Documentation, users will inform you by commenting badly on your instructions. They will also overload your customer support team, and all these unaddressed issues may lead to a premature churn increase.
If you don’t spend time understanding your target users, you may produce documentation with either too many or too few options to follow. They can be overwhelmed by the excess of information provided that lacks usability. Sometimes, the documentation may be too broad, which makes the user feel lost or even too specific to be helpful.
So, if you don’t focus on delivering the correct information for the right user at the right moment, you can lose your client prematurely.
A specialized team of developers is a great advantage of a technology team. These experts are used to being immersed in the product and its solutions, which can also be a challenge when walking in the shoes of a new user, especially if they lack technical background.
It can be challenging to separate what is essential information from what is advanced. This difficulty in knowing what information and journey suits each user best can mislead developers and technical writers into supposing everything is apparent. That may result in technical documentation without going through the basics that a new user needs.
We know some bias will remain, but it is a manageable gap when building your API Documentation. A customer-centric approach to this kind of writing influences every process step, especially when defining the document’s structure.
Since we are talking specifically about the software’s API, the available endpoints must be presented coherently according to the user’s requests. Here’s an example: suppose that the user needs to generate a Bearer Token through an endpoint that will function as an authenticator to the other endpoints. Therefore, to respect the user’s typical journey, the token generator endpoint must be the first one to be presented and explained.
Each documentation will have a unique structure that depends on the purpose of the API solution, which also has to be presented clearly to the user in its introduction. When you know which users you are talking to and the solutions they are searching for, it becomes easier to define how to present your product and its possible user journeys.
The standard part needs to cover the essential content that every API Documentation must have, such as the response types, how the authentication and authorization are performed, the errors the users may receive while working with your API, the parameters and object descriptions for each endpoint, and examples of requests and their possible responses.
However, there are some orientations that, when followed correctly, will help you attend to your client’s needs while writing your API Documentation. Those instructions can be found in this article on the topics below.
First, it is essential to delimit what is relevant to your documentation and what is not. Here, at Write Choice, we ask our clients the following questions to understand better their solutions and what needs to be documented. We edited the questions so you can feel interviewed and produce your answers and documentation.
These are some of the questions whose answers will help you define how to present your endpoints and guidelines.
The user types of your product are often related to the services you provide, so if they aren’t associated, you can completely separate them on your API reference and create different user journeys to explain them.
At this stage, you have to define what is essential for each user type, and you might notice that your product may have different user journeys that overlap at some point, and it also must be mapped into your documentation.
Once you know who you are talking to and which features and functionalities need to be explained, it is time to separate the information into categories and pages that are easy to navigate through.
Some questions that can guide you while starting a new page of content:
These four questions aim to help you define precisely the scope of the page, the kind of language and detailed information it will require to achieve its goal, and in which order this page will be presented to guide the user smoothly through their journey.
Yuno Docs is an excellent example of a developer portal we created. In this documentation, we constantly worked with the product team to fully understand all the services and features offered in Yuno’s checkout solution.
The API documentation starts with an overview section, which has an introduction page to present the methods, response types, and environments. Then, we dive into the authentication methods and all the details that Yuno consumers need to know to start making requests. To wrap up this overview section, we created a page to present the expected HTTP response codes and a list of reference data for the enum parameters, such as payment method types, passenger types, airline details, and more.
After the overview, we created categories for each resource/service sequentially since, for the Yuno API, there are interdependencies between endpoints. For example, before enrolling in a payment method, the user needs to create a customer, and a customer is required to launch a payment.
Print of the Yuno’s API Documentation developed by the Write Choice’s specialists
For each resource, we started building a page presenting the parameters for that core resource. It is a best practice inside Write Choice because developers can easily understand what that resource represents and the parameters they should expect when making a request related to it or even creating a new one. Moreover, together with the object page, we added a page to present statuses and workflows for each resource for which this was applicable.
After the object, we included the endpoints exactly in a sequence that users should be using. In the case of the Customer resource, first users need to Create a Customer (POST), then they can Retrieve Customer (their by customer_id or external id) with a GET method, and finally they can Update Customer (PATCH) if necessary.
Each endpoint contains explicit descriptions of each attribute and its type. It is also important to mention that each endpoint has a clear description with important information that users need to know, not to say that we always include several examples of requests and responses for each use case.
Investing in API Documentation improvements will always bring numerous benefits, but it is still prevalent to find software companies that don’t spend time or money on it. There are plenty of reasons that make tech teams deprioritize the delivery of clear and efficient documentation to their users, but let us list some reasons why you should start working on it right now.
One of the worst experiences a user can have on any software is not finding what they need when they look for features and instructions that can solve their problems. A well-organized API Documentation system ensures that any user, being coding familiar or not, will find what they need and implement it effectively.
The more you put time and effort into providing an API Documentation with excellent structure and clear language, the faster they will onboard, and you will increase their autonomy, ensuring a five-star experience within every interaction with your documentation.
As long as your software evolves, it would be best to modify the API accordingly. With a well-structured document, managing these updates will get easier over time and will impact your users on a long-term basis. Since APIs are not static and must change according to new requirements and features, an excellent API Documentation structure eases this process.
The time your team invests in planning the documentation is a small fraction of the time they save in the future when they need to change anything on the API. It gets more manageable for your team, but it also helps the user get the updates on the documentation faster and more efficiently.
The learning curve of excellent documentation may take your team a long time. Even if you already have a running API, it always will have room for improvement. But do you know the best plan to leverage it to the next level?
That’s why we founded Write Choice. We want to revolutionize how tech companies teach their products to their customers through top-notch technical documentation and content. We do so by providing our clients a collaborative and highly skilled team to import our know-how into your team and deliver the best documentation even faster.
Do you want to have our expertise inside your team? Our specialists are ready to help you on this link. Let’s schedule a call to revolutionize your company’s documentation too!
© 2023, White Choice. Todos os direitos reservados.
