Free and Open Source API Documentation Tools

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

Drupal for Developer Portals

by diliny.corlosquet / 5 December, 2019
Why choose Drupal as the foundation for your developer portal?

In our previous blog post we discussed the advantages of when to use a content management system (CMS) versus a static site generator (SSG). In this article we outline the elements of why Drupal is a good candidate for building your developer portal and why we use it as the base for our SaaS product. Drupal 9 is the current version of Drupal. To learn more about migrating Drupal 7 sites or upgrading a Drupal 8 site to Drupal 9 see DevPortal Migration.

Community of Developers

Drupal is supported by a community of dedicated contributors who continually innovate to stretch its capabilities both in terms of functionality as a content management system and in terms of usability by developers, site administrators, and... Read more

Visual Solutions to Improve User Experience of Developer Portals

by gyongy.gora / 23 October, 2019
FAQ What visual solutions (apart from the ones in our previous posts) can contribute to a better user experience? Should you use animations on a developer portal? How can you make API cards look better and how can you differentiate categories visually? How can you make a developer portal more understandable and transparent? Solutions Interactions, micro animations

Too many animations can have a disturbing effect on your users: they might lose focus when concentrating on moving elements instead of focusing on important content. Functional micro animations can help to improve the user experience.

Examples:

Small interactions can visually express that an element is interactive. E.g. the hover effect of buttons, icons, links, menu points or cards shows that they... Read more

Basic Graphical Elements of Developer Portals

by gyongy.gora / 22 October, 2019
FAQ What kind of icons can you use on your developer portal and where can you apply them? How do colors and typography affect and improve the usability and transparency of a developer portal? What kind of images and illustrations can support and visually improve dry technical content? What if you don’t have a brand font, an image bank or an own icon pack? Where can you find these and which viewpoints should you consider when selecting the elements that are right for you? How can you make code sections prominent and handy? Experience and advice Icons

Icons play an important role in the UI of websites and of developer portals.

Functional, UI icons

Functional icons, commonly known as system icons or UI icons, visualize different functions and information in a... Read more

Overall Design Style of Developer Portals

by gyongy.gora / 14 October, 2019
FAQ Is there an actual design trend for developer portals? Should the developer portal have the same look as the corporate site? Should the developer portal use the same branding as the corporate site? Should the developer portal look like an eye-catchy “marketing site” or like a clean, technical documentation base? How can you avoid that the developer portal looks like a site with only dry documentation? How can you improve this visually? Experience and advice Actual design trend

Similarly to the way trends change year by year in web design, the preferred visual styles of developer portals also change. Nowadays, it is really popular to use illustrations in certain page sections. These colorful, aesthetic illustrations can spice up the, dry, technical content and pages... Read more

Developer Portal Layout and Navigation

by gyongy.gora / 10 October, 2019
FAQ What kind of layout is the most common on developer portals? Is there a suggested layout for devportals? Are there design patterns that help understand the site and improve the overall usability? What design solutions help users not to get lost in a huge amount of code and documentation pages? What design solutions make it easier to navigate the devportal? Experience and advice 3-column layout

“If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.” (Taken from: The ten essentials for good API documentation)

Stripe presents extensive documentation... Read more

Devportals on Different Devices: Responsiveness

by gyongy.gora / 1 October, 2019
FAQ Should my developer portal be optimized for mobile devices? Should we have a separate design for mobile devices or one design that works responsively on every screen resolution? Experience and advice Desktop and tablet

In case of developer portals, mobiles are mostly used for browsing, reading documentation or watching tutorials. Most portals are optimized for desktop and tablet, which means that they look and work the best on these devices. When you are working with code it is handier to use a display, keyboard and a mouse than tapping a small screen, so it is not surprising that for developers the first choice of tool is a desktop computer: they can copy the code snippets or try them out instantly.

Internal portals - which make up a huge part of all developer... Read more

Developer Portal Design: Increasing clarity and trust for a better developer experience

by kvantomme / 1 October, 2019

UI design is a key component of a great developer portal. But what makes a great devportal design? How can you avoid obvious pitfalls? What are UI elements you could use to improve the developer experience (DX) of your devportal?

This blogpost summarizes key design principles as introduction to our new series on great developer portal design, where we will explore the role of design in developer portals, focusing on UI design and graphic design aspects that help to create a better developer experience.

Two years ago we wrote a blogpost in our developer portal strategy series about 7 Trust Signals That Help an API Succeed. In it we mentioned the importance of the production quality of a devportal:

“Developers might not consciously think about this, but a good... Read more

Engage Users: Inspire, Educate, & Authorize

by kata / 27 March, 2019

Driving API adoption is crucial for a developer portal. In this post, we’ll explore how you can strengthen user engagement right from the very start of your API program regardless of whether you have a public-facing, partner or internal devportal. (Examples in this post are taken from public-facing devportals.)

Users, context and content are key

When we at Pronovix start working with a client, we usually conduct user research, compile a content inventory and look into the context of the API program. In short: we focus on the information architecture (IA) first. Nomen est omen: the main audience of developer portals are the developers, but our projects show that decision makers and business managers often play an equally important role.

How can you integrate all your... Read more

Analyzing the API docs and DX Patterns in the Best Telecommunication Developer Portals

by monika.alfoldi.zorgo / 6 August, 2018

The telecommunication sector was one of the earliest adopters of APIs and today it is one of its most important and largest markets. During our research we examined both telecommunication carriers and companies like Nexmo and Twilio, which are often referred to as API vendors. What we were suspecting from the number of publicly available developer portals among the two groups has been confirmed by other resources too: as a developer or a system integrator will most likely choose an API vendor when in need of an API, these vendors are more likely to invest highly into their public facing developer portals. More traditional telecommunication carrier companies on the other hand benefit greatly from internal and partner facing developer portals, as they can facilitate the development of... Read more