At funda, we strive to simplify our developers' work with initiatives like Golden Paths: development templates that streamline the process. Aleix Domènech, Staff Engineer and creator of Golden Paths, explains how they benefit our workflow and how they might help yours.
This blog was originally published on July 15, 2022. The content has been reviewed to ensure it's still up to date. Now, let's dig in!
What are Golden Paths?
About three years ago, born from the need to further empower our developers to take full ownership of their services, we came up with lighthouse architecture. After defining this architecture, we needed to find a way to ensure that our teams were not solving problems that had already been solved by other teams.
We wanted to provide our development teams with best practices and recommendations that could help them in their day-to-day work whilst still promoting their freedom and independence.
Upon further investigation, we landed on this blog post from Spotify's engineering department. In it they detail how they came up with the Golden Path concept, in essence a compilation of various How-to guides written by engineers to speed up the onboarding time in the company. Additionally the name comes from Dune, and as a nerd I totally bought into it! I absolutely recommend giving that post a read – it won’t take too long, and it is incredibly insightful.
See also: Game changer: the benefits of having a lighthouse architecture
We immediately felt that this Golden Paths could be something that would help us provide standard practices without intruding too much in teams' own decision-making processes. This way, teams could retain their freedom of choice while we could maintain an appropriate level of consistency throughout our platform.
Golden Paths at funda
We adopted the Golden Path concept that Spotify created to help disambiguate teams and maintain good consistency around team boundaries. In other words, we recommended ways to achieve common goals such as messaging, authentication and authorisation, email processing, etc.
Golden Paths are a great way for developers at funda to develop and build stuff: stuff that works well and integrates seamlessly with the rest of the platform, and that the reliability team knows how to support and troubleshoot should things not go as planned.
We have generated Golden Paths for most of the activities our developers might encounter daily. For example, imagine you just started working here, and there is some new feature that you are supposed to create. In the old days, you would have had to ask your teammates how to proceed, and they would have had to guide you through every step of the way until it was internalized enough that you could do it on your own.
With the Golden Paths in place, you can log in to the developer portal, hit that search box with your question, browse through the different Golden Paths available to you and pick the one that best matches your requirements.
How do they work?
To make our Golden Paths available, we needed to find a framework that would allow us to create, update and distribute the required documents and attached tools to our developers. Once again Spotify came to the rescue with their open-source tool Backstage.
Backstage is a fully-fledged developer portal that includes a software catalogue, a documentation repository, software scaffolding templates and other features. It is also possible to browse through a very long list of third party extensions, meaning that this tool can be customised to match your organisation's requirements. In our case, we added the APIs component, which adds UIs for both Swagger and AsyncApi so that our developers do not need to remember a bunch of different URLs to access them, since they can all be found centralised in Backstage.
Tech Docs is Spotify's documentation-as-code tool baked into Backstage. It is based on MarkDown, a lightweight markup language widely used to write documentation in, for example, software code repositories. It also supports adding mkDocs plugins to add an extra bit of functionality and features to your documents.
Practically, a Golden Path is a document in our Tech Docs archive which contains:
- A description of the goal we want to achieve.
- Background information around the topic.
- Diagrams of possible implementation strategies.
- A specification with dos and don'ts.
- A step-by-step guide on how to make it happen.
- Relevant scaffolding templates so developers can focus on the fun part: code, not setting up infrastructure and CI/CD facilities.
It can also include additional information around the topic that document the decisions and assumptions taken in the main Golden Path in the form of appendixes.
Examples: Golden Paths in action
One example of this is the Golden Path of inter-service messaging. In it, we describe how messaging works within funda, which (sub)patterns are supported in our organisation, what events and commands should look like, how to manage contract changes – including versioning – and a step-by-step guide on how to broadcast a new event or subscribe to different services' messaging topics.
Another example is our Golden Path about the UIs of feature services. These independent services provide our customers with UIs to use our platform. The Golden Path describes a feature service's UI, how it integrates with the rest of the website, how to create a new one, and, of course, a scaffolding template. This template will generate a new code repository with fully configured CI/CD and infrastructure so that you can jump right into coding.
Where are we now?
Golden Paths are relatively new to funda, and we are still very busy creating new ones and updating those we have already started. At the same time, we are migrating our CI/CD infrastructure to a more cloud-native friendly approach. We are planning to make our Golden Paths a central part of the puzzle, that is, the funda platform, to further leverage the already growing list of benefits the lighthouse architecture and the new funda platform have brought us.
Who is doing all this? Right now, our Platform team is working hard to create more scaffolding templates for all of our Golden Paths. As the team's primary responsibility is standardisation and developer satisfaction, we felt that there was no team more appropriate to help Staff Engineers materialise the ideas of the Golden Paths into actionable tools in order to generate code from our developer portal.
Conclusions
The other day, I was having some coffee in the office, close to the cupboard where all the sweet stuff is kept (of course!). I could not avoid eavesdropping into a conversation between two colleagues from different teams. They were referring to some projects their teams had been working on.
They used several names that are part of the available Golden Paths. Besides the fact that they are being used, I could not avoid noticing how much faster the colleagues' conversation went, as they both understood immediately what the other one meant simply because they now have a shared language.
Situations like this confirm that the concept of Golden Paths is taking off, and the feedback I have received tells me that the developers are quite positive and excited about them. Hopefully with this blog post we can give back and pass the word around, just like Spotify did for us.
See also: 5 reasons we believe in testing our products as a team
Question?
Do you have a burning question for Aleix after reading this blog? Feel free to reach out to him via email.