For developers taking on a new team member, often the most difficult part of onboarding is not so much the code but the business logic. Amidst bug fixes, customer escalations, feature work, and other responsibilities, a developer seldom has the time to prioritize writing documentation. This leads to critical documentation becoming outdated—if it exists at all—and disparate documentation across multiple mediums. At worst, this creates tribal knowledge that only resides in one or a few team members.
Naturally, this has a negative carry-on effect for both existing and onboarding developers. It greatly increases the time-to-effective metric for new developers trying to learn the codebase and existing developers working in an unfamiliar part of the codebase. The lack of business logic documentation increases time spent in self-learning. It also increases the frequency of often-asked (and never documented) questions.
There is a solution. It’s called CodeSee Maps.
This post will dive into how we can use CodeSee Maps to visualize business logic, reducing the amount of time it takes to get developers familiar with a codebase. First, let’s cover the basics of what all this means!
A little bit of backstory
CodeSee’s mission is to help engineering teams better understand their codebase through a visual and action-driven representation. This is achieved through the use of Maps and Tours. Maps are the visual representation of the codebase, showing connections between different parts of the code. Tours are the actionable representation of the codebase, showing notes on particular files or blocks of code, or simply notes to help explain what parts of the codebase are about. Some common use cases for CodeSee include:
- Developer Onboarding: Using Maps and Tours to speed up a new team member’s understanding of the codebase.
- Code Reviews: Visual highlighting of what’s affected by code changes, raising other areas of code that could be impacted.
- Continuous Understanding: As your code changes, so does the knowledge around it. Maps keep that understanding visible as your code changes.
- Collaboration: Maps and Tours make code changes accessible to all stakeholders— technical and non-technical.
Improving Time-to-Effective with Tours
How do CodeSee Maps and Tours address these problems and improve the time-to-effective metric? It doesn’t magically remove the need to do some documentation, but it considerably reduces the effort involved by automatically updating a Map when a code change happens. This dynamically captures relationship changes in the codebase.
The beauty of this feature, when combined with a Tour, is that any notes or explanations that have been included get carried along when the Map changes. There are several benefits, which include the following:
- The documentation delta is much smaller because code and documentation are more cohesively integrated.
- The amount of time needed for documentation is reduced since documentation changes can be smaller and more incremental.
- Better documentation resiliency. As your business logic or code changes, your documentation will spend more time being correct due to the modularity of Tours and the types of annotations you can include.
- Time savings. A lower barrier to documentation changes means less time spent making them. More senior engineers can spend less time on onboarding because the explanation of the code and business logic is built-in.
Let’s translate the benefits into a more tangible example. We’ll use an example company named “Ecommpany” whose ecommerce platform is based on the Python framework, Django. At this point, we’ve installed CodeSee for our repo and have generated our initial map, which looks like this:
One of the key things that a developer at this ecommerce company would need to understand is the workflow for purchasing from the customer’s perspective. The first thing we can do for a new developer trying to understand the customer’s flow from product to purchase is to add some color coding. We’ll add a label that we can use to indicate the primary pieces of the codebase that the customer interacts with directly when making a purchase.
We’re getting closer! As a new developer fresh to Ecommpany, I can at least identify which views a customer will interact with for purchasing. However, many steps happen between finding a product and paying for it. Telling the story of the customer purchase at the code level is where CodeSee Tours comes into play; next, we’ll create a tour and add our first step!
Create a tour by selecting the compass icon:
and then,
which will prompt you for a tour name. Now we’ll add some steps to the tour to show the end-to-end flow of the customer purchase experience. With a little rearranging, we’ve landed with the following steps:
As a developer clicks through each step of the Tour, they can see an explanation of the workflow and how business logic gets handled or resolved.
Wrapping up
Business logic is often the hardest part to grasp when looking at a codebase. Developers know that some interaction triggers other actions, and that lands in a datastore somewhere. Telling the story of how that happens becomes trivial with CodeSee Tours and the automation of CodeSee Maps. CodeSee users can create step-by-step, color-coded, living documentation for their codebases. This significantly improves the time-to-effective metric, reduces developer friction, and improves team morale by lightening the burden of bringing on new team members. CodeSee Maps and Tours also provide a unique opportunity to provide cohesion across more than just the development team!
Coupling labels with Tours allows you to create customized, role-specific walkthroughs. Use Tours to provide a walkthrough for your documentation writers, color code modules that are key to your database interactions, or provide a high-level walkthrough for the business development team. The flexibility of CodeSee allows you to create and evolve documentation that survives not just changes in your codebase but also changes in your business.
