The Qonto Way: One spec to rule them all

As our product grew more complex, it became increasingly difficult to have a complete picture of how everything worked together. And, to keep our pace of growth, we had to find a way to maintain an up-to-date source of truth for all our functional specifications. This article explains how we previously handled specs, the issues we found with that approach, and how we came up with a new one entirely.

What was wrong with “specs by feature”

Our traditional approach to specs was to have a dedicated page for each new spec, where Product Managers would compile a list of expected behaviors for new and existing screens. This approach worked well until the product became more complex, especially when new features overrode parts of existing screens.

As a result, it was challenging to understand precisely how a screen worked and what the potential repercussions could be elsewhere in the app when updating a specific element. The codebase became the only reliable source of truth, and Product Managers had to rely on Engineers to repeatedly explain how screens behaved. This interrupted the Engineers’ focus, causing them to provide quick, approximate answers that led to rework, waste, increased lead time, and frustration.

Building the prototype

To solve this problem, we needed to develop a prototype of a source of truth for specs and designs. Each screen should have a unique source of truth. Therefore any updates made on a screen should be reflected in that one source of truth, instead of on any other dedicated page. Our designs were on Figma, so we kept them there. Writing specs next to screenshots in Notion was actually more work than directly writing spec in Figma. Developers could immediately see the high-fidelity designs with their specs in the same Figma file, with the existing spec right next to the proposed change

To ensure that our specs were comprehensive, we identified four key areas that our previous approaches had missed to include in our new prototype. First, we needed visibility over all a screen’s elements, no matter the conditions. Second, we needed to know how any element behaves without having to resort to asking the engineers to retro-engineer the codebase. Third, we needed to know whether an element is shared across several screens to avoid having a change on one screen make unwanted updates on other screens. And finally, we needed a clear picture of the screen flows with all the conditions to navigate from one screen to another.

Improving and scaling the prototype

In order to onboard all our Designers, we needed to come up with a clear standard that responded to their specific needs on a platform they recognized and used regularly. Now, we have one “Visual Specs” workspace in Figma with folders ordered by theme, and not by team. Every screen belongs to everyone, not just one team. If a team in charge of a specific scope makes a change that will impact another part of the app, they can update the right screens in the right place and everyone will see the change automatically. In this way, our current approach to specs is more comprehensive than before. Each theme folder has one page for each user story.

The content of a user story shows the horizontal progression of the user journey. Vertically, we have all the possible variants of each key screen (error state, loading state, empty state…). The spec cards are the fully exhaustive acceptance criteria for each element where every possible behavior of the element is explained. The key screens will hold most of the specs, and variants will only show their specific specs.

Now, any time we develop a new feature, we create a new branch in Figma and add the new spec cards in a distinct color next to the new elements. Once the feature is finished, these spec cards will be turned into their “live” state, and the branch merged with the main one. This keeps everything clean, up-to-date, and ready for starting a new feature in the best possible conditions.

Performing the full migration

Updating the ways of working in a Tech and Product department can be challenging. Which is where the Qonto Way came in — continuous improvement is at the heart of our culture. We try out new methods with a subset of the team, and if they prove useful, we implement them throughout the entire team. If not, we discard them. When it came to revamping our specs approach, we began at my team’s level and I took the full ownership of the initiative with the support of the Product/Design/Tech team members that are directly implicated in its use. Ideally you want to reverse-engineer enough screens and specs to cover the next feature you’ll eventually work on (I reverse-engineered my team’s full scope so we’re ready for whatever new feature comes our way).

Be sure to demonstrate your (positive!) experience of this new feature and don’t hesitate to promote its benefits heavily to others to get buy-in from the Tech and Product executives.

Once we got the ball rolling, we needed to update the way we worked at scale. We wrote a reviewed set of standards, each geared towards a different team: Tech, Product and Design, with a clearly outlined ownership for each stack.

Once you reach this step you can build your new features in visual specs, consolidating knowledge feature after feature. However, you only get the full benefits of working this way once you’ll have mapped out every last behavior. Depending on your situation, there are two ways to start full-scale mapping (each team can decide to adopt one approach or another):

• Freeze production for a few days on each functional team and ask your Tech team and Designers to retro-engineer the full existing scope. This method has several benefits: the team concerned gets full domain knowledge, including new joiners, and you get 100% clear about how everything works — no more blind spots.
• Retro-engineer only the parts you plan to update just before creating a new feature. This ensures that you’re not missing anything, and you can start building the new elements on top of this new source of truth. The downside to this approach is that you’ll never have the full picture mapped out.

Conclusion

Our new specs process has revolutionized the way we work, bidding adieu to codebase “cave diving”. By creating a single source of truth for specs and designs, we have created a workspace that is easy to use, is accessible to all team members, and provides accurate and up-to-date information on all our screens and user stories. We’ve saved time, reduced reworks, accelerated new-joiners onboarding, and provided a more comprehensive picture of how everything works together.

We have built the equivalent logic for the back-end, you can have a read on it here

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!