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 developer portal can be a signal that you are not cutting corners, and that you are committed to your API program. Regular updates to your portal, through blog posts, event postings, and documentation updates show that you are (still) investing in your APIs.”

The work we’ve done these past 4 years building devportals for our customers has given us the experience we needed to build the UI designs for our devportal product. In this series we want to generalize the most important insights and share them with you to give you the background knowledge you need to understand what makes a great devportal design.

Design in support of content: content-driven design

In marketing, design is often used to overwhelm or distract audiences — to induce an artificial craving for a product that might actually not be that valuable for a customer. This is the type of manipulation that developers hate and that gave rise to the myth that “developers hate marketing”. But developers are also just humans who like to interact with well designed, or even good looking tools.

The difference is that developers will ultimately need to integrate with your APIs and they will experience any faults in your API design or your support infrastructure first-hand. Developers look under the hood, so they tend to value the workings of the software over its looks.

That is why on a devportal design should serve the content to help underline the message of this content, to make it easier to understand what APIs you provide and how they can be used. Design is not the star of the devportal, it is the scenery. A mind-blowing scenery will give more power to the content, but the content needs to be king.

Reduce friction & frustration

Each user arrives on your portal with a specific goal in mind, be that researching and discovering your APIs and products, evaluating what you offer with a certain task in mind or specifically looking for answer that they know you will provide.

It is crucial to discover who your users are, what structure and elements your main audiences will expect to find, and to organize the devportal in a way that will remove as much friction as possible. When UI design supports the content architecture of your developer portal, and brings UX design to life, it will enhance the overall experience and usability of the devportal.

Professional but technically playful

Developers appreciate tongue-in-cheek references to developer pop culture. It shows that you are on top of things, that you have energy to invest in a little frivolity. If that playfulness comes in an otherwise professional setting, it also shows that you are serious but don’t take yourself “too” seriously. Playfulness is also an act of humbleness that - in the right dose - inspires trust: “These people understand me, they are my crowd”.

Technically playful design can take many forms. In its strongest form this could be coding related animations, or images that are beautiful but that also have a hidden meaning to developers. In the least intrusive form technical playfulness might be no more than a set of icons that lighten up the content.

It is important to not overdo things, because some of the business personas visiting your devportal are not coders. Too much technical signaling will alienate them and can negatively impact their impression of your API products.

Branding

API programs sometimes start as skunk works, in which a small group of rogue developers launch an initiative to build APIs. These teams don’t often have the budget to fully support the developers that want to use their APIs. While the enthusiasm of a self-driven core team can —to some extent— make up for a lot of problems in documentation and support, still most developers are wary of underinvested projects. Too many great APIs have disappeared when management decided not to double down on a particular API strategy. Wasting the efforts of all the developers that invested in an integration with the discontinued APIs.

For all these reasons it is important to demonstrate if an API initiative is part of a company’s core strategy. Devportals should be in harmony with a company’s brand.

There are temporary exceptions to that, though: maybe marketing research has shown that an overwhelming majority of developers in your target market believes that your organization did not yet succeed in building a credible API program. In that case it might be worth launching a distinct API campaign under a separate brand, to build credibility. Production quality then becomes more important, it must show that this start-up faction has the means to execute on its vision. Later on you can merge this new campaign back into the main brand.

Consistency

Technical limitations can make it hard to optimize user journeys across tools, resulting in an information architecture that confuses visitors. One of the most common antipatterns in the API industry is the “Frankensite”, when multiple tools with varying levels of themeability are cobbled together, delivering an inconsistent design experience.

It is crucial to provide a consistent experience throughout your devportal infrastructure. The look and feel of your tutorials, guides, and reference documentation should be consistent with the design of your landing pages, support infrastructure, and release notes.

Find out more about the 3 most common devportal antipatterns in one of our recent webinars:



This article is the introduction to our UI Design Guide for DevPortals, an article series sharing our insights we gathered throughout the years we've been building developer portals, spiced up with an analysis of the current trends and patterns in devportal design:

Published:
1. Developer portals on different devices; responsiveness.
2. Common devportal layouts: advantages, disadvantages. Navigation solutions and suggestions regarding layout.
3. Actual devportal design trends; brand consistency. The balance between aesthetics, content, and functionality.

Upcoming:
4. Basic graphical elements that support functionality, like icons, colors, imagery, and typography.
5. Other visual solutions to improve the user experience: animation, onboarding, process and data visualization, and social media elements.



About the author

Kristof van Tomme

CEO, Co-founder

Kristof Van Tomme is an open source strategist and architect. He is the CEO and co-founder of Pronovix. He’s got a degree in bioengineering and is a regular speaker at conferences in the API, DevRel, and technical writing communities. For a few years now he’s been building bridges between the documentation and Drupal community. He is co-organiser of the London Write the Docs meetup, and cheerleader for the Amsterdam and Brussels Write the Docs meetup groups. This year he is working on a number of new initiatives to help API product owners learn from their peers (API the Docs and the API product owner masterminds).