Developer onboarding is a crucial part of any successful, growing team. As your organization expands, the importance of smoothly and quickly onboarding new team members will naturally increase. But onboarding is not a one-size-fits-all process; having a variety of approaches will help people with differing personalities and skillsets adapt effectively to your team.
CodeSee codebase maps are customizable code diagrams that automatically update along with your codebase, with the ability to visualize insights spanning your codebase. Plus, codebase maps offer intuitive, interactive features, like Tours, to help drive the onboarding process.
So, you might be wondering: Why would I need a Tour?
Why should I create a Tour of my Codebase?
Tours allow you to guide folks through your codebase, step by step. They can be created, edited, and ultimately shared asynchronously, so you can communicate important details about sections of the code and highlight key code flows—really, whatever is most important to get your incoming teammate on the path to success.
Let’s take a step back for a moment and go over what we mean by a Tour!
What is a CodeSee Map Tour?
A Tour is a contextualized onboarding experience, created using the Tour feature on the CodeSee platform. Tours allow you to personalize the information on your Map for a given user or group of users. With CodeSee's interactive code tours, you can guide your team through the sections of the codebase that are relevant to them.
Think of Tours as a customizable guide to the codebase—a capability that's especially powerful when you consider applying it to different kinds of Maps.
Check out the example Onboarding Map. At the top, you’ll see the Tour interface. The left side contains a dropdown for you to select your desired Tour. In the middle, you’ll see the steps within the Tour, allowing you to jump to any step in the Tour quickly. On the right, you’ll see the “Start Tour” button. Go ahead and hit that button.
This will take you to the first step in the Tour. Each step of a Tour is linked to a specific section or file in your codebase, allowing you to guide your user through areas of your codebase.
Just as there is no one right way to tour Italy, Tours are not a one-size-fits-all experience. Instead, we recommend that you add multiple Tours to your Map, one for each individual or group that will use it.
How should I customize my tours?
Below are a few ways to differentiate your Tours for maximum impact.
By team ownership
One way to create different Tours is to create them by team ownership. For each team that works with the codebase, allow them to create a Tour that focuses on the specific needs, responsibilities, and areas of interest. Depending on the structure of your organization, this may give you Tours such as a Front-End Tour, a Back-End Tour, a DevOps Tour, and so on.
This division of labor has several benefits. First, it is inherently contextualized to the needs of that team. As a new teammate onboards onto that team, they will be presented with the information specific to that team in an order that makes sense according to their shared knowledge and mental framework. This gives the new teammate a jumpstart on understanding the codebase, team lingo, and mental models.
Additionally, involving each developer team in creating the Tour creates a sense of ownership. This is especially helpful for organizations that are rolling out Maps. Getting each team to create a Tour on top of a Map increases the likelihood that they will be able to derive value from the Map itself.
We recommend providing a basic structure to follow for each team when creating the Tour. The Tour should give a brief overview of what happened in the past, where each group is now, and where they’re headed in the future. Additional points of interest can be covered, but we would recommend that a Tour for a new developer be expected to take no more than 10-15 minutes to go through.
A per-team Tour is not the only option! The developer level is another way to create personalized Tours within or across teams.
By developer level
Since developers at different levels have different experiences and responsibilities, customized Tours by developer level will have a much greater impact than a generic Tour for all levels. We recommend three levels of Tour: one each for junior, senior, and lead developers.
For a junior developer, the key is to focus on what they need to accomplish for day-to-day development. This means knowing where to look for information on setting up your local environment, tips for debugging, and which parts of the codebase have the best code quality (and are thus worth imitating).
For a more senior developer, the Tour should shift more to gaining architectural and bigger-picture understanding. Focus on the component or API hierarchy, lead the developer through the product architecture, and especially make a note of interactions or integration points outside the product.
Finally, for the lead developer/architect, zoom out to focus on the overall company architecture. Use the Tour to guide the new developer through the organization’s various teams and interactions and note upcoming goals and initiatives that the developer will be expected to participate in and possibly lead.
The benefit of creating tiered Tours is that as developer responsibilities change, they can be pointed to the appropriate Tour. As a junior developer grows, they can use the information in the senior developer Tour as a form of training. Additionally, suppose a lead developer needs to debug a critical issue in a new codebase. In that case, the information in the junior developer Tour could save them a significant amount of time.
One more way to create Tours is to focus on the product; that is, to create them by feature.
A feature-focused Tour is a quick way to help a developer adopt a customer-centric perspective on the codebase and to keep the entire organization aligned around the goal of delighting customers. Additionally, this will help the development team understand the codebase from a product perspective.
Feature Tours should cover both current and upcoming features. When discussing current features, we recommend adding information about the customers that use this feature. Include information about when a customer uses this feature. Essentially, this is a higher-level user story. Check out this sample feature planning map. Upcoming features can discuss the intended impact as well as priority.
Along with upcoming features, it’s also helpful to highlight areas of known technical debt. This helps developers understand that this cleanup work is coming down the pipe and avoid propagating this debt to other parts of the codebase.
Now, it's time to get started
We’ve covered the basics of how Tours can improve and personalize your developer onboarding experience. With these differing approaches in mind, it’s time to start using CodeSee to build Tours for your team!