BLOG: Applying Golden Path
For new developers starting in a team, finding the way around can be difficult. Even if you know and can work in programming languages used by your new team, understanding how to apply them and how to use the supplied tooling can be hard.
Our team Fleet Control at Autonomous Systems work with API services based on a microservice architecture. As an autonomous development team, we have responsibility for all parts of the devops chain from writing source code, via continuous integration pipelines to deployment in the cloud.
Not Finding the Way?
An essential task for a new developer in a team is to understand how the team has designed its services, how the tooling to build is used and what the deployment architecture looks like. All of these are based on decisions taken by developers in team over time, perhaps years.
But if there is no available and explicit documentation to find the basis for design choices, you are left discover it by talking to colleagues, researching chat conversations or issue comment threads.
How can we document our preferred design and capture the choices made when building a microservice, with the purpose of decreasing diversity?
How can we transfer this knowledge to new developers to make the onboarding process easier?
Inspiration
We looked around and found an article from Spotify on their work on improving alignment and developer experience when they found themselves in a similar predicament and referred to situation as ’Rumour-driven development’.
To tackle this, Spotify started creating developer tutorials with recommended and opinionated way of creating services and using the existing tooling. Each tutorial is a step-by-step description of how to write and deploy a service, written with the aim to be complete and include all required steps. The tutorials are then published in their developer portal for everyone to consume.
Finding our footing
Based on the inspiration from Spotify, we decide to try to create our own Golden Path. We needed a microservice and a documented step-wise journey to develop and deploy the service.
We decided to start with some code we had for a Spring Boot microservice, written in Java 11, as use a basis for our Golden Path. It implements a simple REST API representative of the domain we work in, but in a simplified way. Typically, we send parts of the code together with an API description to potential new hires and consultants and ask them to implement some small part of the API. We then go through the resulting code during the interview process.
Retracing our steps
The first step was to study how our current services are created and extract the essential patterns and tooling used. In this first iteration, we could not include every functionality or capability of our existing services, so a selection or sometimes a simplification of the existing content had to be made.
Once the core material was gathered, it was divided down into 7 topics, each a part in the puzzle of building a microservice and how to deploy it.
The topics were then further broken down into stepwise instructions, with accompanying detail or motivations. For some steps we have also added extensions or variations to illustrate something the developer might not encounter in every case, but it would still be useful to understand.
The resulting material was then committed to a git repo.
Use as learning journey
Starting as a new developer in a group using modern software development can be a daunting task. We assign a mentor from the team to guide, but once the initial tasks of getting account and various access in place and the development machine up and running, what’s next?
With the Golden Path, a new developer in our team can now fork our git repo and follow the step by step tutorial. This process can take two to three weeks, but gives the possibility for the developer at his/her own pace to get acquainted with designs and technologies used in the team.
We have found it very useful for the new developer to discuss the content after each part with the mentor. The discussions not only enhance the understanding for the new developers of the new material, but it also provides valuable feed back that can be used to improve the Golden Path.
Base for further exploration
Apart from getting new developers to become productive, we have also found the Golden Path useful as base for improvements of our ways of working.
For instance, we used the Golden Path application to learn how to automatically generate Swagger API documentation from our application source code. Having a small but functioning application makes it easy to experiment with how the Swagger tooling works, and in the future the Golden Path application could also be used to demonstrate how to write good API documentation.
Another example has been working with how we write Dockerfiles for our Java applications. We have improved the usage of layer caching in the Docker image to reduce build times.
Now with the release of Java 17 LTS, it will be interesting to try out and experiment with records to see how they could simplify and improve our design.
Summary and future steps
We will continue to update our Golden Path as we learn and update our currently supported services.
In the future, we hope to be able to continue with providing a more tooling to simplify the setup of new projects, based on our Golden Path, enabling simple and faster ways to experiment with new services.
