Onboarding Doesn’t Have to Suck
with Ana Margarita Medina
Onboarding can be frustrating…
New jobs can be both scary and exciting. A new workplace means a fresh start, with new opportunities. But it also means that you are starting over again. Making new work friends. Building relationships with your new manager and new co-workers. Learning new processes. Familiarizing yourself with a new tech stack. Even if you’re a seasoned software engineer, it can get pretty overwhelming. Not only do you need to learn about internal processes, you also need to make sure that your machine is set up in just the right way so that you can start being productive as quickly as possible.
That process can be a pain in the butt on a good day, and downright stressful on a bad day. Sometimes installing the right tools and getting the right access to install said tools can take hours, if not days, depending on where you work. This type of thing can leave a poor first impression, which is not a great look for that company.
Today, we’ll talk about the challenges that developers face when onboarding, and the importance of creating a good onboarding experience for developers. We’ll also examine available tooling, and onboarding models.
The many faces of onboarding…
One of the challenges when setting up a developer machine is software installation. Many organizations provide new employees with machines having a “base image”, containing a common set of software tools used by everyone at the company, regardless of their role. This software includes but is not limited to:
- Browser
- Email client
- Productivity tools (e.g. docs, spreadsheets, presentations)
- Collaboration software (e.g. Slack, Teams)
- Video conferencing software (e.g. Zoom, Teams, WebEx)
- Security software (e.g. VPN, anti-virus software)
This means that developers must often install development tools on their own. And depending what type of organization they work at, the installation experience can be very different. It can be one of the following…
The Vault
Sea otters at a bank vault. Image generated with AI via Dalle3.
- Developers are allowed to install software only if it’s from an approved list
- Usually managed by the security team, and approvals for software might take a REALLY REALLY REALLY long time
- Common in organizations that maintain high levels of security and compliance because they’re dealing with really sensitive data
- e.g. finance and healthcare
Red Tape Tango
Sea otters dancing the tango with red tape while in front of a computer. Image generated with AI via Dalle3.
- Although developers can only install software from an approved list, they can go through a white-listing process to add more software to the approved list
- Might not be quite as locked down as “The Vault”, but due to processes and policies, approvals for software might take a while
- Common in organizations that maintain high security and compliance standards, but have more wiggle room
- e.g. SaaS companies, consulting companies
Wild Wild West
Sea otters in a wild west scene, wearing cowboy hats while working on computers. Image generated with AI via Dalle3.
- It’s a free-for-all! Developers can install whatever they want
- Usually lacks processes or guides on how to get started
- Common in small, fledgling organizations, where security isn’t a concern…at least, not yet
- e.g. small startups
What goes into a developer environment?
That’s all well and good, but what exactly goes into a developer environment? The list below is by no means exhaustive, but it should give you a good idea of the types of tooling that developers want/need:
- Language-specific software development kits (SDK), such as the ones for Python, Go, and Java. After all, you need a compiler or interpreter for your code, a package manager, etc.
- An integrated development environment (IDE) and plugins, so you can write your code efficiently
- A terminal and default shell, with the ability for developers to install/configure their favourite shell
- Git for source control management
- Various command-line interface (CLI) tools, depending on what your team does. These may include things like kubectl and CLI for the cloud provider used at the organization (e.g. gcloud for Google Cloud, and az for Azure)
- Virtual environment tools, such as Docker and VirtualBox.
- Supporting tools required by your team, such as OpenSSL, cURL, Wget, Postman, and Homebrew
In addition, developers need access to certain SaaS tooling. Although these tools are not physically installed on a developer’s machine, they are likely required by developers as part of their day-to-day work. These may include:
- Access to cloud provider accounts (e.g. Google Cloud, AWS, Azure) and resources (e.g. Kubernetes clusters, storage buckets, etc.)
- Remote Git repo access and CI/CD workflow tooling access (e.g. GitHub, GitLab, BitBucket)
- Access to Observability back-ends (e.g. ServiceNow Cloud Observability, Honeycomb, New Relic, Splunk, Grafana)
- Other system access
Now, wouldn’t it be nice if there was a way for developers to:
- Install the tools that they need
- Make customizations to their liking (within reason)
- Have access to all of the systems that they need in order to do their jobs
…ON DAY ONE?
Platform engineering to the rescue!
Fortunately, this is absolutely possible, thanks to platform engineering.
While there are many different interpretations and definitions of platform engineering, our favorite interpretation defines platform engineering as the next step in the evolution of DevOps.
DevOps gives us the fundamental principles of collaboration, Codify All The Things™, Automate All The Things™, and rapid feedback loops.
SRE applies DevOps principles, with a focus on customer impact and reliability.
Platform engineering is an extension of SRE. While SRE is focused with external customers, platform engineering takes things a step further and also focuses on internal customers — that is, the developer.
Developer experience, or DevEx, is one aspect of platform engineering that we’re exploring today. But what is DevEx?
DevEx is about how developers feel, think, and value what they do.
But why does it matter?
Why DevEx Matters
According to the DevEx in Action: A study of its tangible impacts report by Dr. Nicole Forsgren et al., published on ACMQueue:
“Developers who find their tools and work processes intuitive and easy to use feel they are 50 percent more innovative compared with those with opaque or hard-to-understand processes. Unintuitive tools and processes can be both a time sink and a source of frustration — in either case, a severe hindrance to individuals’ and teams’ creativity.”
Furthermore the report highlights that:
“…there is a difference between simply writing code and writing code in an environment that is optimized for writing code. Environments that are optimized for writing code are efficient, effective, and conducive to well-being, and rely on the right mix of tools, practices, processes, and social structures. These environments help developers:
* Get into the flow and minimize interruptions so they can focus and solve complex tasks.
* Foster connections and collaborations so they and their teams can be creative when it matters most.
* Receive high-quality feedback so they can make progress.”
With that in mind, let’s look at some onboarding approaches and tools that can improve DevEx for onboarding.
Environment Setups & Tooling
Before we get into tooling, let’s look at two types of environment setups.
Self-contained environments
- Developer machine has base tooling only
- Developer tools are accessed via containerized or virtualized environment
- Runs either locally, on the cloud, or a combination of both (e.g. cloud-hosted dev container and local IDE)
- e.g. GitHub Codespaces (containerized), Vagrant (virtualized)
Local environments
- Developer tools installed and accessed on local machine
- Requires more local compute and storage, compared to running a self-contained dev environment on the cloud, where your workstation is basically just a terminal
- A configuration management tool (e.g. Ansible) can be used to configure and install developer tools locally
The above environment setups can be supported by some of the tools below.
Note: The tools listed below are listed alphabetically and are a subset of available tooling supporting DevEx.
Ansible is an automation tool by RedHat, with both community and paid offerings. Ansible can do all kinds of automations, including deployment orchestration, configuration management, and even Terraform-esque things like deploying and configuring cloud infrastructure.
Backstage is an open source framework for creating developer portals, and is part of the Cloud Native Computing Foundation (CNCF). It also offers a paid SaaS version, through Roadie.io. It has a wide variety of plugins available through its plugin directory, and also allows users to develop their own.
DevPod is an open source tool by Loft Labs that allows you to create containerized development environments (dev containers) running on various types of infrastructure (e.g. Docker, Kubernetes, or various cloud providers). DevPod can be linked to your favourite IDE, whereby the IDE runs on your local machine.
Codespaces is a cloud-hosted containerized development environment by GitHub. Think of it as running a full-fledged containerized development environment in your browser tab, including VSCode.
Kratix is an open source framework by Syntasso for building platforms which provides Kubernetes-native API-as-a-service out of the box. Kratix allows SRE teams to deliver pre-configured, reliable, consistent, and compliant Kubernetes resources via an API that is easily consumed by developers. This is accomplished through a Kratix Promise. A Promise is an encapsulation of a software capability.
Port is a SaaS developer portal tool. Like Backstage, it also offers a plugin directory, and allows users to create their own.
Vagrant is a tool by HashiCorp that’s used to manage and build virtual machine environments. Like Ansible, it has both community and paid offerings. Vagrant has the concept of a provider, which refers to the location in which the virtual environment runs. Out of the box, Vagrant ships with support for VirtualBox, Hyper-V, and Docker providers; however, Vagrant is extensible and allows you to write your own providers for other types of virtualized environments.
Sample onboarding workflows
How do we apply these tools for developer onboarding? Let’s look at two example workflows.
Self-contained onboarding workflow
“Self-Contained” onboarding workflow
The above diagram shows the onboarding flow for a self-contained developer environment, using GitHub Codespaces.
With GitHub Codespaces, the platform engineering team is responsible for creating the Codespaces configurations, and environments can be easily spun up and brought down. Since the whole environment is remote, you don’t need to worry about having the right amount of processing power, storage space, and developer tooling running on your local machine. The tradeoff here is that you will probably need to manage different codespaces for different repos or even different branches.
The Developer arrives for onboarding day, and then:
- Kicks off the onboarding process by going to a designated wiki, which takes them to the a GitHub repo
- From there, they’re able to bootstrap a virtual environment running on the cloud hosted by GitHub. This environment contains all of the tools and configurations needed to start adding value to the team.
- Once their environment is created, they are able to work on their first PR.
Local install onboarding workflow
“Local Install” onboarding workflow
The above diagram shows the flow for a local install onboarding workflow.
Remember that unlike in the self-contained onboarding workflow that we saw above, the developer does all of the work on their own developer machine, so making sure that you have a good amount of storage and compute power is essential. But it also means that you have all of your tools at your disposal all in the same place, and you don’t need to rely on a network connection to do development work.
Here, we’re making use of a developer portal tool (e.g. Backstage, Port). The developer portal tool uses GitHub Actionto orchestrate the onboarding, and Ansible to install and configure tooling onto the developer workstation. Note that instead of Ansible, you could use any other configuration management tool. Similarly, you could use another CI/CD tool in lieu of GitHub Actions.
In this flow, the developer will:
- Kick off the onboarding process from a developer portal
- The developer portal tool triggers a GitHub Action
- The GitHub Action in turn kicks off an Ansible playbook
- The Ansible playbook installs and configures tools on the developer machine, in much the same way as it would do on some production server
- The playbook also sets up the appropriate permissions and access to various systems and services that the developer will need to access during their time on that team
- At this point the developer also has the option to kick off workflows to install additional corporate-sanctioned developer tools via the same developer portal, following a similar process to the initial onboarding setup, via steps 7–9 above.
Final Thoughts
Before we wrap up, we wanted to leave you with some tips for building a better onboarding experience for your developers.
Keep Balance in mind. Balance the ease of installation of software with security and compliance constraints. Are you a Vault, Red Tape Tango, or Wild West setup? Do you want to provide your developers with a self-contained or local dev environment setup?
Remember that DevEx is never done. There’s always room for improvement, so check in with your newly-hired developers to get feedback on their recent onboarding experience while it’s still fresh in their minds. Similarly, check in with all developers a couple of times per year to get their thoughts on onboarding.
Don’t work in isolation. DevEx is a team sport. You need feedback from InfoSec to ensure that you address security requirements. You also need to work with developers to understand what types of tools they need, and why. Finally, talk to other platform engineers outside of your organization to see if you can pick up any interesting tips, tricks, and best practices
Don’t forget the humans!! Use the “buddy system” for onboarding, pairing a new hire with a seasoned employee as the go-to source for onboarding questions. You’ll also want to ensure that you create and foster relationships in between your new hires, and leadership, along with some teammates in other key departments (e.g. sales, marketing, product). Remember that it’s always great to make friends in other departments, because you never know when these friendships may come in handy. Finally, fave a place (e.g. Slack channel) where new hires can talk to one another, meet each other and ask questions
By keeping DevEx in mind, choosing the right tools that suit your organization, and having good onboarding practices in place, you’ll be well on your way to providing a great onboarding experience to your developers.
Now please enjoy this lovely photo of Adriana’s rat, Katie Jr.
Until next time, peace, love, and code. ☮️ ❤️👩💻
PS: check out this fun little 1-minute video that Ana and I put together.
