by adam.balogh / 16 May, 2022

We explored free and open-source API documentation solutions, and compiled the results of our research in this post.

Definitions

An Application Programming Interface (API) is a set of clearly defined methods of communication between various software components. Organizations share their APIs so that developers can build applications that use the services of their software.

API documentation describes what services an API offers and how to use those services. Good quality documentation is essential to developer experience, which in turn will impact the adoption and long-term success of an API.

We wrote this post for API providers: To provide an overview of free and open source tools for companies that want to share, update or customize their API docs or developer... Read more
by christoph.weber / 1 December, 2021

APIs in a modern enterprise are rarely uniform or all of the same type. The multitude of API types can be due to organic growth, mergers and acquisitions, or any number of other reasons. Once a company decides to fully manage and document their APIs, put emphasis on an API-first strategy, and streamline digital governance, they start looking for a developer portal that can support their needs. Customers often ask us whether Pronovix's Zero Gravity developer portal can document APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more. The short answer is, yes, the Zero Gravity (ZG) developer portal can document those too. Let's look at what is possible in a bit more detail with examples.


Five common API types, and how they can be documented in... Read more

by kathleen / 31 January, 2019
Learning journeys along the downstream developer journey

In previous posts we have been researching how developers who use a public API move on a specific developer portal. We looked at how their background (skills, interests, approaches, previous experience with the specific portal and its API products) and tasks at hand can define at which stage of the downstream developer journey they enter first.

At APIdays Paris 2018, Ronnie Mitra gave an insightful talk on how to improve API documentation and learning experiences, for which he gathered inspiration from the Dreyfus model of skill acquisition.

In this post, we’ll dive a little deeper into the whole topic and illustrate Ronnie’s conclusions by giving an overview of content and DX elements we imagine would help... Read more

by kathleen / 24 May, 2018

Posts in this series:

Introductory post Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals Analyzing the API Docs and DX Patterns in the Best Telecommunication Developer Portals Analyzing the API Docs and DX Patterns in the Best Media Developer Portals Analyzing the API Docs and DX Patterns in the Best Media Developer Portals 2



This series will focus on finding the best, most innovative and interesting practices on existing developer portals independently of their toolchain.

While we can see immense differences in how companies organize the API docs on their developer portal, some provide us with great examples on how documentation can... Read more

by kvantomme / 29 March, 2018

For the past three years we’ve been giving our answers to the following questions: What is a developer portal? Who are its stakeholders? What is developer experience? How do you improve it? What is the MVP for a developer portal?

If you are new to API documentation, that might be a lot to digest...

That is why we created 2 options to get a summary of our research: you could ask us to do a developer portal strategy workshop with your API team (we do these for free for potential customers), or you could join us for a developer portal rundown at a meetup near you, Kristof has done similar presenations in San Francisco, Portland, and London.

If you don’t want to wait until we visit a meetup near you, you can now also read this transcript, with links to in-depth... Read more

by diana / 12 February, 2018

Organized by the Center for Information–Development Management, IDEAS is a two-day industry conference including five 60-minute concurrent sessions in two tracks. The theme of this winter's conference was Writing Well, where we spoke about API Documentation Best Practices.

In this session we talked about different aspects of API documentation:

Why API documentation plays an important role in the API economy The difference between API documentation and developer portals The target audience of API docs Developer portal components and best practices for arranging and writing content for each Usability considerations, like interactions, readability and personality Ways to edit and keep your documentation up-to-date, workflow considerations, and the docs like code... Read more
by kathleen / 21 December, 2017

What information is absolutely essential on a developer portal? What kind of API documentation do you need? Is there a best practice that can be followed when launching a developer portal? In this post, we share the insights we've learned working on developer portals the last couple of years.

A quick look at some (API) developer portals will demonstrate that they can be very different in architectural structure and layout. That is remarkable, because most of the portals not only need to provide similar end results, they also address comparable audiences.

We formulated 11 questions that can help you define the content of your portal to address the documentation needs of your stakeholders. To illustrate how it can be done in practice we built 3 mock sitemaps for developer... Read more

by kathleen / 23 December, 2016

The main purpose of Platform Software Development Kits and Helper/Client Libraries (we’ll use “SDKs” to address these collectively in our writing) is to accelerate and simplify development. A well maintained SDK is a trust signal that indicates the level of support and usage of your API for a language, framework, or development platform. So indirectly SDKs work as social proof, that indicates how many communities are already using your API.

In this post, we’ll look at how the developer portals in our research sample included SDKs. We’ll examine their functions, describe where we found them in the site architecture and deduct best practices.

We’ll discuss what kind of SDKs the Portals in our sample used. We’ll analyze their choices and evaluate them against the... Read more

by steve / 13 December, 2016

Twilio is regarded as one of the API industry’s leaders, so when, after five years, Twilio changes the documentation format on their developer portal, everybody wants to know why. Jarod Reyes and Andrew Baker (both developers of Twilio's developer education team) gave a presentation about the reason for the changes at SIGNAL 2016. Because we found them valuable and wanted to share them with our developer portal mailinglist, we’ll summarize their findings in this blog post.

1. Know what developers don’t need: Narrative vs Code

Twilio considers API documentation to be a product in its own right, not just a supplement of “The Product”. Because developers need documentation to integrate with an API, it plays a key role in the developer experience and overall quality of service. It... Read more