In our Developer Portal Design Guide series, you will read about common design patterns, get an insight into our project work related experiences, and learn how we tackle the design of a developer portal user interface.
Why did we start researching design on devportals?
We found that dedicated research can help us to write more objectively about design patterns, and decide what the common practices are —based on statistics.
We examined 70+ developer portals from different industry fields, and also pulled in DevPortal Awards 2018 nominees and winners. We gathered information about various design aspects, like layout, responsiveness, color schemes, typography and the usage of graphical elements.
We will stay away from the most basic design principles but focus on developer portal specific advice instead, and give related examples.
The article series will cover the following topics:
- Developer portals on different devices; responsiveness.
- Common devportal layouts: advantages, disadvantages. Navigation solutions and suggestions regarding layout.
- Actual devportal design trends; brand consistency. The balance between aesthetics, content, and functionality.
- Basic graphical elements that support functionality, like icons, colors, imagery, and typography.
- Other visual solutions to improve the user experience: animation, onboarding, process and data visualization, and social media elements.
Part 1: Responsiveness
- 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 portals - can usually be reached only from the secure network of the company. This again implies that users mostly work on their usual workplaces and the work device is mainly a desktop.
Despite all this, we should always consider users working on a touchscreen. Every interactive graphical element should be tappable and not just clickable. We suggest using at least 44px x 44 px sized interactive elements throughout the portal consistently because this is the minimal size that is easily tappable with 1 finger. Also, thinking about readability and visibility, the body texts should be around 15px and the images optimized for retina screens to obtain a good user experience. But let’s talk about these later.
Responsive, dynamic layout
Regarding the structure of the developer portal, we suggest using a responsive, dynamic layout, where the components rearrange themselves and adapt to the different screen resolutions, filling in all the space. These fluid layouts look great on every device and browser.
The dynamic layout allows a highly flexible display of the content. It helps to deal with the different content lengths/amounts and provides an opportunity to easily add more content, such as:
- textual content (e.g. blog posts or API releases),
- elements (e.g. images, tables, code snippets),
- sections (e.g. a CTA section),
- boxes, cards (e.g. more API cards),
- pages (e.g. a new API summary or a documentation page).
Page Builder Kit
Visual page builders in a CMS (for Drupal: Paragraphs, Layout Builder, for Wordpress: Divi, Visual Composer page builder, etc.) also help you to reach the desired look of a certain page and create a responsive layout. You don’t even need programming skills, just add the predefined page sections and elements, and adjust their appearance. If set properly, the portal will be responsive and look good on different screen resolutions. In some page builders you can even set how a section should behave and look like on various devices.
With a visual page builder you can usually:
- Change the appearance of the sections.
- Change section order.
- Add new sections.
- Temporarily hide sections.
- Delete sections or cards.
- Duplicate sections.
- Change the splitting of sections (e.g. use 2 cards instead of 3).
When we use a responsive, dynamic layout, the mobile version will look similar to the desktop one, but the content, the different boxes and sections will be rearranged. When the screen width passes a breakpoint, they drop under one another.
However, there are solutions that we need to re-think completely. For example, the look and usage of the header, menu bar and the sidebar navigation (if there is a sidebar menu) should be totally different on mobile.
Because of the lack of space, we suggest creating a unique header for mobile, where the menu points are combined and appear inside a hamburger menu dropdown. We often use meaningful icons on the mobile version instead of the longer texts and big buttons (e.g. login, logout, profile, search) to spare space.
Some examples on great solutions:
The sidebar also needs modifications because on mobile we can’t use a 2 (or more) column layout. In most cases, the mobile version of the sidebar navigation can look almost the same as the desktop version but it should work differently. For example, it can be hidden by default and opened up by clicking on an icon.
The mobile version of large, multi-column tables and the swagger UI can also be improved as the whole data table won’t fit into the small screen width. The easiest solution is to keep the data table as it is and use swipe gestures to scroll through the table horizontally or simply just shorten the table.
You can read about other solutions for responsive data tables in this article.
If there is no mobile support at all (e.g. in case of internal developer portals), don’t forget to make a page that informs the users about this.
We hope that this article post provided you with useful thoughts and samples about the behavior of developer portal interfaces on different devices and explained why we prefer a fluid, flexible layout.
What comes next? In the upcoming article, we will dive deeper into the structure of developer portals: we will show examples for 3-column and centered layouts, and talk about navigation solutions and common industry patterns regarding developer portal page types.
If you have questions or would like to work with us, contact us!