The Qonto Way: One spec to rule them all — for back-end as well

Jean-Philippe explained in a previous post why having a single, trustworthy source for functional specifications of the user experience was key to improving the development experience. We’ve saved time, reduced reworks, accelerated new-joiners onboarding, and provided a more comprehensive picture of how everything works together.

After the success of our front-end centralized spec, we decided to also apply the idea of “one spec to rule them all” to the back-end team. This article explores how back-end technical specifications were created, maintained, and used; details the shortcomings of our previous approach; reveals how we leveraged learnings to improve the situation.

Writing diagrams, all for naught

At Qonto, work for a new feature begins with investigation and decision-making, to reduce any uncertainty early on. During these initial steps, back-end engineers rely on API contracts and sequence diagrams to explain their proposed solution. The design documents of past releases would be stored and searched by engineers seeking information later. This approach was enough at first, but we were relying on documents tied to a specific release that would never be updated, and soon become obsolete.

As Qonto grew to develop more complex products and tackle more efforts concurrently, the pace at which documentation became obsolete also increased. Each new release only documented its own specific changes, resulting in a fragmented and incomplete picture of our system. Our codebase remained the primary source of truth, making it difficult for engineers to fully grasp the architecture during the design phase. The same problem that had plagued front-end was also affecting back-end, and so it became clear that it was in our best interests to apply their learnings to our work.

Simple actions, at the right time

Inspired by the front-end team and their “one spec”, we realized that the documentation lifecycle needed to align with that of the product and codebase. Just as both of these elements are constantly evolving, the back-end documentation should do the same. To begin with, we decided to prototype a solution in an upcoming improvement and measure its effectiveness.

First, we dedicated time to creating up-to-date technical documentation specific to the product targeted for improvement, focusing on the two innermost layers of the C4 model (Components & Code).

It was very important for Jean-Philippe and I that the back-end technical specifications acted as a one-stop shop for information, so we designed an enhanced sequence diagram where additional information and links are embedded for anyone looking to dig a bit deeper. That includes things like API contracts, 3rd-party provider documentation, and banking network specifications.

Second, instead of creating new documentation for proposed changes during the design phase, engineers now directly make annotations on top of the existing one. They use red highlights on parts that will be deleted as part of their new feature, and green highlights for the parts that will be added.

As there is now a unique source of truth for each flow, anyone who reads it understands how it works, and perfectly visualizes ongoing changes.

Third, a reminder is scheduled for after the release, asking engineers to remove the red highlights and unhighlight the green ones, to show how the system currently functions.

Validating the prototype

The new approach led to significant improvements. Armed with good documentation, we noticed that engineers were better prepared for the design phase, and empowered to create robust solutions. The outcome was easy alignment, less rework, and faster delivery. Most importantly, we finished the iteration with an updated source of truth that continues to portray the complete picture of our architecture.

Two unexpected effects were also observed: product managers engaged in more detailed discussions, leading to better functional specifications, while front-end engineers gained the autonomy to drive other improvements without the need for back-end backup to understand constraints. At that point, it became evident that other stakeholders in the company needed access to our new documentation too, and that the final solution should reflect that need in both its philosophy and design.

An accessible source of truth for everyone

A clear picture of back-end flows is useful beyond the back-end team: web, mobile, data engineers, and product managers all benefit from it. There should be only one source of truth, and only one version of it. One that is easily accessible by anyone, whether they are engineers or not. So, we opted for Whimsical, a workspace which is perfect for drawing sequence diagrams, as well as facilitating creativity.

To make the information truly accessible, it was fundamental that all specifications lived in the same place and were organized by functional scope, so that anyone could find the information they were looking for, immediately.

From 1 functional scope to over 50

Getting a team to agree on delaying the start of a new feature or improvement for 2 or 3 days is a hard ask. But what if the upside is saving more than that time during delivery, thanks to less rework? What if the benefits would be long-living, impacting the certainty and speed of all improvements to come? That was the pitch that we repeated to all of our cross-functional teams.

The first prototype was built and tested within my team. Having achieved success locally, it was then a matter of showing that it could help other scopes as well. After preparing a standard that introduced the new exercise with clear guidelines for quality, both Jean-Philippe and I supported other teams in creating their own living sources of truth. We then guided them in putting the right actions in place throughout their development processes.

One by one, the teams tried the new approach, and fell in love with it! With a legion of promoters, it was no longer a question of getting the buy-in of yet another team willing to try it out — we had teams reaching out on their own to ask for support to implement it themselves. And, as of today, there are over 50 functional scopes from all our back-end teams that use the new processes for technical specifications.

Reaping the benefits

Forget putting engineers through retro-engineering and hours of investigating the codebase for a simple question. Now, information is accessible to anyone. Making sure that there is a “go to” place for documentation is invaluable to Qonto’s ability to iterate fast, and safely, on our products.

This effort, alongside its sibling initiative led by front-end engineers, tell the story of how our culture of continuous improvement helps us challenge our ways of working, no matter the size of the change. We’re delivering faster thanks to less rework, and we achieved that by equipping every single employee with the knowledge they need to succeed.

Thanks to jean-philippe denis for collaborating with me in this initiative and co-writing this article!

About Qonto

Qonto is a finance solution designed for SMEs and freelancers founded in 2016 by Steve Anavi and Alexandre Prot. Since our launch in July 2017, Qonto has made business financing easy for more than 400,000 companies.

Business owners save time thanks to Qonto’s streamlined account set-up, an intuitive day-to-day user experience with unlimited transaction history, accounting exports, and a practical expense management feature.

They stay in control while being able to give their teams more autonomy via real-time notifications and a user-rights management system.

They benefit from improved cash-flow visibility by means of smart dashboards, transaction auto-tagging, and cash-flow monitoring tools.

They also enjoy stellar customer support at a fair and transparent price.

Interested in joining a challenging and game-changing company? Consult our job offers!