As a developer joining an existing project with other developers, you face several challenges. You’re wading through a pool of unfamiliar code, trying to connect what you encounter with the documentation you’ve been given, and you’re parsing the tribal knowledge that naturally evolves with any project over time. With lots of effort—and perhaps some luck—you’ll establish a mental model of the project that matches the rest of the team’s.
How long it might take you to get there fluctuates with the project’s level of maturity and the team’s level of diligence when it comes to onboarding. When the onboarding experience is poor, new developers can lose a lot of time trying to get acquainted with the project. In addition, that initial excitement to jump in and get their hands dirty will slowly erode.
What would it look like to build a better onboarding experience for developers—one that gets new developers up and running faster?
With the advent of tools like CodeSee codebase maps and interactive product tours, the onboarding process becomes measurably shorter and more valuable. In this article, we’ll look at how you can improve the onboarding experience, ultimately shortening the time-to-effective metric for new developers.
Visual Documentation for Faster Understanding
Tools from CodeSee serve several functions when it comes to developer onboarding. A CodeSee codebase map is a visual representation of your entire codebase. This visual representation is automatically created when linking a repository to CodeSee and it dynamically changes as your codebase changes.
Naturally, this reduces the time needed to perform the following tasks:
- Manually create application diagrams
- Write documentation
By adding notes to your codebase map, you can highlight what’s important in your codebase. You can also use labels to segment different parts of the codebase for different roles. For example, you can highlight which sections would be salient for frontend developers versus backend developers.
With a codebase map, wrapping your head around a new project is no longer a slog. There’s no more reading through pages of documentation, sharing bookmarks, or spelunking through deeply nested code to piece together a mental model. All developers on the team have access to a shared visual representation of the code flow.
Removing the Need for Human Walkthrough
While codebase map can level up the onboarding process tremendously, it’s still only part of the story. A codebase map does the job of pulling together a conceptual model for every member of the development team, but new developers need additional guidance on what they should be looking at first.
Normally, this is where you’d have an existing team member partner up with an onboarding buddy and walk through each step of the onboarding process. The downside to this traditional approach is now you have one person being less productive to help another person become productive.
A more efficient approach would be for a new team member to walk through the onboarding process unattended and come out on the other side ready to contribute code. This is the approach you can take with Interactive Product Tours. A Tour is a layer on top of a codebase map that provides a self-paced introduction to your codebase. In practice, a Tour is very similar to having an onboarding buddy describing what to look at and where to find it, as well as any important details about the codebase.
Better yet, you can create multiple tours for a codebase map, enabling context-specific walkthroughs for other groups or seniority levels. For example, in your development team, junior developers likely need a Tour to help them contribute code as soon as possible. However, a new developer lead or architect may need a Tour for a higher-level view. Tours allow you to cater to specific personas in your development team and across your organization.
In addition to efficiency, product tours also bring consistency to onboarding. The onboarding experience—what’s covered, what’s highlighted, what receives additional explanation—often depends on the team member providing the onboarding tour. An interactive product tour in CodeSee removes that variation and inconsistency, ensuring that new developers always get what they need, without bias and without omissions.
Keeping Documentation Updated with Automation
Documentation is arguably one of the most self-beneficial deliverables we have as developers. However, despite the clear benefits, we often get stuck with tight deadlines and deprioritize writing documentation in favor of shipping an implementation. Over time, this leads to tribal knowledge—important information that everybody ought to know but nobody has written down. As the amount of project tribal knowledge increases, the need for human-guided onboarding increases. Otherwise, how would the tribal knowledge be transferred?
CodeSee codebase maps and tours can alleviate some of this burden through automation. When you push changes to your codebase, the associated codebase map automatically updates and carries along any Tours that you’ve created. Contributors don’t need to take extra steps to update the documentation because CodeSee updates itself. With the automated updating of documentation comes a reduction in tribal knowledge.
Now, at any point in time, any developer—new or existing—can know the current state of the codebase’s conceptual model.
Conclusion
Onboarding new developers takes time and resources, but it is essential to getting new developers contribution-ready. Traditionally, an effective onboarding process requires a human walkthrough, and that means a temporary loss of productivity. Even then, there is no guarantee of consistency between the onboarding from one developer to the next. We have little confidence that the new developer’s mental model of the project matches the rest of the team and properly prepares them for contributing.
CodeSee can help you achieve more effective developer onboarding while using less of your resources. CodeSee automates the creation of the conceptual model, ensuring that every developer is working with the same vision. Interactive product tours ensure that every developer receives the same onboarding experience, built on top of an automatically updated conceptual model. Ultimately, onboarding with CodeSee tools frees up time for existing developers and reduces the time-to-effective metric for new developers.
