API
Documentation
Overview
Banking Circle is an API-first company. Even though Banking Circle Connect, the online portal, is used by most clients. The majority of payments happen through API integrations. The API documentation site is a critical interface between Banking Circle and its clients, it helps our clients integrate into our APIs and thus use our services.
The previous iteration of the API documentation site was created in a hurry without any considerations for usability or user experience. My task was to bring the current documentation site into something our users would be delighted to use.
Role
Senior UX
Specialist
UX Research
Information Architecture
UX & UI Design
User Testing
Time
Mar-May
2022
3 Month project
Team
Sigrid (PO)
Yakang (Insights)
Kristian (UX/UI)
Paul (Frontend dev)
Lau (Frontend dev)
UX/UI Audit
The first step I took in the redesign was conducting a design audit. I took the entire site apart, documenting every component used and breaking those even further into its building blocks (colors, typography, and shapes). While doing this, I also noted down all the areas where the usability and user experience of the site needed improvement.
Below are some screenshots of the API documentation site when I started the audit:
And some of my initial questions, ideas, and recommendations:
Collaboration with Insights
While I worked on the UI audit, Yakang from the Insights team created a market research study and delivered a report which included the most common features offered by the best API documents in the financial industry.
Findings
After analyzing both the audit and the market research report, and talking with more internal stakeholders these were my main findings:
The API documentation site needs to cater to two user types:
Decision makers: We expect the site will get reviewed by CTOs or persons with similar decision-making roles, of possible future client organizations. For them, the site needs to offer a quick overview of our solutions, services, and the technology we work with. It should help them decide if Banking Circle is the right partner for their organization.
Software developers (Users): Once a decision has been made to partner with Banking Circle, our API documentation site will need to cater to our second user type. These are software developers and other similar individuals with the task of integrating their systems with ours. These users’ needs are more complex, the site needs to function as a work tool for them.
Therefore we need to provide a great developer experience (DX):
Both of our user types are technical, and what we know about our users is that they work with code. This does not mean they want to write more code (Don't Make Me Think), what they want is fast and easy access to code examples.
The second thing we are considering to provide a good developer experience is understanding that as developers our users are responsible for their products. They need to trust us, any problems with our products will affect theirs. And the way we gain their trust is by providing documentation that feels safe, intuitive, and reliable.
(Don't Make Me Think)
Action plan
Once we had a good idea of the user needs, together with Sigrid (Product Owner), we decided on what we needed to do:
Improve the information architecture, ease of navigation, and content:
IA: Information is where the user expects it to be, and it’s memorable.
Navigation: The user can get to the desired information fast and easily.
Content: The user has all the content they need (code examples, updates, etc..).
Improve the accessibility, responsiveness, simplicity, and visual design:
Accessibility: The user does not want to struggle while reading the content or navigating the site.
Responsiveness: The user wants to review the content from different devices.
Simplicity: The user does not want to be distracted by elements they don’t need to see.
Visual design: The user wants to feel our products are robust and reliable.
Detailed plan
Once the top goals for our re-design site were decided we went deeper and started to make decisions on how to achieve these goals.
Information architecture:
The content is divided into Guides and API Reference and organized in a more intuitive way.
Ease of Navigation:
Topbar navigation gives access to the high-level areas.
Sidebar navigation gives an overview of all content and fast access to it.
Search function gives fast and intuitive access to all content.
Landing page includes all 3 navigation aspects, giving the whole content overview plus fast and intuitive access to it.
Content:
Content will increase, and include more code examples.
Change log section will provide access to new content and changes for power users.
Accessibility:
Font change proposed to increase readability (Inter).
Colours are reviewed to match accessibility contrast ratios.
Navigation is possible with a keyboard.
Responsiveness:
The design takes into consideration different devices and screen sizes and devices.
Simplicity:
The content is the protagonist, no other distractions in the design.
Visual design:
The style is robust, serious, and consistent to provide a sense of reliability and trustworthiness.
Data:
An analytics tool is needed to understand our user’s behavior
This will help us to make decisions in the future and measure our success
First iteration
Once the full action plan was in order, I took it into Figma and started working on the first iteration. From the visual side, the idea was to align it with our other customer-facing product (Banking Circle Connect), the online banking portal.
The first thing we defined was the new information architecture, the focus as noted in the plan was to separate the Guides from the API reference. The reason behind this is that those two different types of content are used by our two different users, and this way our software developer users can more easily find what they are looking for without having to go through all the guides.
Finally following the new IA, I produced the first mockups:
Internal user testing
The advantage of designing for developers, while working in an engineering-heavy organization is easy to access test subjects. Our internal developers also deal with APIs and API documentation sites in their daily work, so they were perfect to help us with user testing.
The goal of the user testing was to test the new improvements in information architecture, navigation, visual design, and content. For this we decided to have two types of test subjects with two different tests:
Unstructured interviews with senior developers in our team, the plan was to show them the new designs and ideas we were working on and gather their feedback.
Usability tests with new developers, we were lucky to be testing near the start of a new month so we had a couple of new developers who were not very familiar with our APIs, the test we designed consisted of observing them while they tried to integrate to our API using the redesigned API docs site.
Findings
The feedback was mainly positive, however, the testing provided us with some important findings:
Guides need to be step-by-step. We learned that developers have an easier time integrating when the guides they are using follow a step-by-step format.
Schema needs to be easier to use. We learned that the schema of an API is very important to developers, we had previously been relying on the schema design we were getting from our API documentation tool, however, this tool was not very friendly to use once on the API site. So a decision was made to make our own design for it.
More code examples are needed. We knew this before even starting testing, but it was good to have this assumption validated.
In terms of information architecture, navigation, and visual design, the user testing was positive and the results showed that the changes were in the right direction.
Design system
While I was working on this project, my colleague Kristian was leading the work on defining the new visual style for our online portal Banking Circle Connect. We had already collaborated on the definition of the building blocks for our new visual style (Typography, colors, shapes, space, and base layouts). The next step was starting to build components.
The API documentation site was the perfect project to test out our new design system, because of its simplicity it did not need too many components. So it was a low effort task that would help us to validate our new style with our stakeholders.
After defining all the components needed, we worked together to redesign them in the new visual style. These new components formed the base of our new design system Bricks UI.
In parallel, our frontend development team started coding the new components, and we used Storybook to help us with the collaboration.
Second iteration
Finally, with the new components ready, I dove into creating the mockups for the second iteration (now with a dark mode option):
Stakeholders review
Once ready I presented the new design to our stakeholders. The presentation was received positively and I was invited to present the new design widely to other departments in Banking Circle.
Implementation and next steps
After the design was refined, I worked with Lau and Paul (frontend team) to get the implementation going. We were running with a few experiments and hypotheses for some of the changes we created so it was important to build tracking into the new design as a way to measure the success of these.
The site went live and you can check it out here: https://docs.bankingcircleconnect.com/
As for the next steps, the goal is to hear further from our users and gather their feedback, so our next efforts will be focused on opening the ways of communication with them. Offering opportunities to provide feedback on the overall site but also on specific guides and references.