Creating a smooth engineering on-boarding experience at cove.tool

A detailed look into the on-boarding experience for the software engineering team at cove.tool

With cove.tool’s recent Series B funding, we’ve had a strong focus on growing the software team so that we can continue to quickly expand our product offerings. Consequently, we’re continually updating our on-boarding processes for new software engineers to ensure that new hires have a smooth transition into their new roles. In this article, I’ll describe the evolution of on-boarding for software engineers at cove.tool.

Early On-boarding Process

When I joined cove.tool, the software team consisted of 1 full-time engineer and the CTO, who was still coding full time in addition to his other responsibilities as CTO. On my first day, after a few minutes of HR-related paperwork and introductions to the team, I was issued a MacBook that already had the majority of necessary applications installed (Slack, VS Code, and so forth). After linking my GitHub account to the organization, I was directed to the main code repository (at the time, we were operating under a mono-repo structure; more on this later) that contained a README on how to run cove.tool in a local development environment and was directed to get the application up and running.

Over the course of the day, I worked through the various steps in the README as I worked to set up the environment locally. At the time, it felt like every other step introduced different challenges because of version conflicts, various assumptions about installed but missing packages, my lack of experience with Mac OS, and so forth. Fortunately, because we were a small team at the time, I was easily able to lean over and ask many different questions to eventually get up and running by the end of the day.

Over the next few days, I slowly became acclimated to the development process — being assigned tasks, opening pull requests, deploying code to staging, and coordinating testing before releasing changes to production. A consistent theme during this process was continually asking questions and taking notes to refer back to.

Moving to a formalized on-boarding process

Approximately six months after I started, we were scheduled to have two new software engineers join the team. In preparation for their start, I created a new “on-boarding” document using GitHub’s Wiki. The initial page was just a place to store the notes I had compiled during my time working on the team, plus a rehashing of the information contained in the README that I initially used to set up my development environment. Not fully comprehensive, but a start.

The on-boarding experience for the new software engineers was very similar to my own experience, but with a bit more documentation to refer to. As they configured their machines to get the application running, we encouraged them to contribute to the Wiki so that future engineers would have even additional reference material.

We eventually transitioned to running our development environments using Docker. I used this transition as an opportunity to deprecate the instructions listed in the README and completely rewrite the GitHub Wiki page for setting up the local development environment. What previously consisted of a day of installing various dependencies to run the application locally simply became a matter of docker-compose up after cloning the repository.

On-boarding the next round of software engineers went even smoother because we had more documentation of our processes, a Dockerized development environment, and multiple members on the team with familiarity on how to setup the development environment. With each new software engineer, we continued to expand the Wiki, including information related to development processes, potential pitfalls when setting up the environment, and details about various parts of the code base; consequently, the amount of time necessary to get up and running continuously decreased.

As the team and the application continued to grow, we made the decision to move away from a mono-repo structure and to instead create separate code repositories for different parts of the application. This change made development easier for a number of reasons, but it also introduced some additional steps for running the application locally. We continued to note these changes in the GitHub Wiki used by the software team, but it was decided that a company-wide Wiki would also be useful. Eventually, the entire cove.tool team switched to using Slab as a central knowledge source. All of the existing GitHub Wiki pages were migrated to Slab, and we deprecated our use of the GitHub Wiki.

Current On-boarding Experience

The current on-boarding process for software engineers is now much more formalized and well documented. Before their first day, new engineers are asked if they would prefer to use Mac OS or Linux (which I have since switched to myself). On their first day, new engineers are directed to an on-boarding guide, which is simply a Slab document that links to various other documents for setting up their development environment, outlining the development process, and a list of first-week objectives.

Additionally, new engineers are paired with an on-boarding “buddy”, who is an established member of the team and serves as a point of contact for any questions they may have, whether that be about team dynamics, questions related to setting up their development environment, and so forth.

Getting the development environment running is still basically docker-compose up (of course, some challenges always present themselves when setting up a new machine). By the end of the first day, new engineers have their machines ready for development.

Throughout this process, we encourage everyone on the team to make any necessary updates to our Slab articles to ensure that the processes are always current. We especially encourage new engineers to include any additional or special steps that they had to take when setting up their machines. We’ve found that this approach continues to reduce the amount of time necessary to get up and running.

Key Takeaways

Having written documentation of processes is important, no matter how small. I was extremely thankful for the instructions included in the README when I was initially setting up my machine when I started because it afforded me some autonomy on my first day (I didn’t want to feel as if I was asking too many silly questions). When a team is very small and it is easy to ask questions, less detailed documentation is likely sufficient. However, we’ve found that as the team has grown, having more detailed documentation that can easily be updated by anyone on the team is extremely beneficial. Encouraging new team members to expand upon this documentation with solutions to their questions has also helped to ensure that our processes are well-documented and always up to date.