A nine-point strategy for developing a successful API documentation portal

Below is a strategy for developing a successful API documentation portal. By following these steps, you can create a plan for building a documentation portal that meets the needs of your API users, and supports the goals of your organisation.

Overview of the steps

Step One: Determine your audience

For example, you need to know:

• Will it be developers, business users, or both groups, who will be using the portal?
• What is their level of expertise?
• What type of information do they need?
• Do they use one programming language over another?

Knowing who your audience will help you to design content that meet their needs.

Step 2. Define your goals

You and your organisation need to know, what is the purpose of the portal?

What is it that you want to achieve? For example:

• Is it to provide a comprehensive guide to your APIs, or just an overview?
• Do you need to educate users on what can be achieved by using your APIs?
• Are you trying to help developers integrate your APIs into their applications?

Knowing this will help you identify the areas that will require attention. It will help you prioritise your efforts. And it will also help you plan the content and structure of your documentation.

Step 3. Gather the requirements

Talk to the stakeholders and understand their requirements.

You’ll probably discover:

• What different types of users you have
• What they want to achieve
• What tasks or jobs they want to get done
• What features they need in the API and the portal
• What types of documentation they expect
• What tools or platforms should the portal support?
• What terminology or processes you’ll need to explain

Step 4. Choose a documentation toolset

You need to have a tool that is a good fit to your requirements and goals. There’s software that can help you create and manage documentation for your APIs. For the reference content, there’s Swagger and Postman. For the onboarding and other content, there’s specialist applications like ReadMe, Redocly, and to an extent, GitHub and GitLab. There are also some good help authoring tools and content management tools.

You also need to choose a format for your documentation.

Do you want to provide static HTML documentation, or dynamic documentation that developers can interact with?

Do you want content that can be generated automatically from your API code?

Do you want to take a docs-as-code approach?

Step 5. Plan the structure and the content

By this we mean define the information model for your portal.

This is about the navigation and organisation of the content.

So think about the user journey.

What are the steps that will take a developer to a successful outcome?

This is where you identify the types of documentation you’ll need to provide.

As a guide, here’s the documentation set that Google recommends its developers provide for what it calls “curious beginner users”:

• A conceptual guide to build a deeper understanding of the underlying technology.
• Cookbooks to explain how to accomplish a specific task.
• API reference information to provide details on all the elements in an API.
• A Getting Started guide to push a curious reader through the first few minutes of use.
• Tutorials and Colabs to convert a reader from curious investigator to active user.
• A one-pager that encapsulates the essence of a technology onto a single page.
• And case studies that show how users successfully employed this technology in the real world.

This stage involves planning the content for each section of the portal – deciding how you’ll divide the documentation into sections, and identifying the topics that need to be covered in each section.

Step 6. Create the documentation

Now it’s time to write and edit the content.

Make sure all the content is clear, concise, and easy to understand.

Some information might be in people’s heads, in experts’ heads. So that knowledge needs to be captured and written down.

You could create a projects team dedicated to writing the content. If that resource is available. One approach is to have some of your API development team write the content. But they might not write it clearly. And they might not have the time to do it either.

You could also bring in outside resource, such as Cherryleaf. We can work on some, or all, of the API documentation. When a Technical Writer create the content, it will be written clearly, and in a consistent manner. It will be well organised. And it will require less time from the Subject Matter Experts.

Step 7. Test and refine

You might need to improve any existing content that already exists. That content might be accurate and complete, but it might not be very usable.

We recommend you test the documentation portal with users and gather feedback. Then use this feedback to refine and improve the documentation portal. You might also need to test the validity of the APIs themselves.

Step 8. Publish the documentation

At this point, you should be a live site that is findable, usable, and useful.

Step 9. Maintain the documentation

You’ll need to maintain the documentation, so it stays accurate. You could enable developers to provide feedback on the documentation and the APIs. This feedback will help you improve the documentation and the APIs. You might need to look at your analytics and carry out more usability testing from time to time.

Summary

Follow these steps, and you should have an API documentation portal that will be useful to your developers. Of course, Developer Relations is more than just the documentation. There’s promoting the API and supporting your community in other ways. But the documentation is a fundamental part.
If you need help

Cherryleaf provides API documentation writing services for API providers who want to:

• Get more people using their APIs
• Have fewer developers face problems when they make requests to the APIs

Contact us for more information.