VIDEO
Shanea Leven (CEO and Founder at CodeSee) talks about why onboarding to your company’s code is hard, and shares tips, tricks, and tools to make this easier. She shares advice for the team, advice for the onboarding, and advice for continuous onboarding.
Like what you see here? Our mission-aligned Girl Geek X partners are hiring!
- Check out open jobs at our trusted partner companies.
- Watch all ELEVATE 2023 conference video replays!
- Does your company want to sponsor a Girl Geek Dinner? Talk to us!
Angie Chang: We’re here with Shanea Leven, the founder and CEO at CodeSee, a developer tool that helps developers and teams better onboard, refactor, and understand code bases. And before starting CodeSee, she led teams that delivered high quality products and features for leading companies including Google, Docker, eBay, and CloudFlare. Welcome, Shanea.
Shanea Leven: Thank you so much for having me. I’m really, really excited to be here. I’m excited to give this talk. As Angie said, I’ve been in dev tools for more than 10 years.
Shanea Leven: One thing that I know about the the experience is that it has always suck onboarding to a new code base. Every developer, whether you are at a new company or contributing to open source if your application isn’t hello world, you must onboard to that code base. And so therefore you must like learn the code base and learn how it works before you can actually modify it. And I showed up today with a secret <laugh>.
Shanea Leven: Are you ready? I figured it out. And the secret is, in order to learn a code base, you need to pair, you need to pair all the time for all time 24/7. And that’s the end of the talk. <Laugh> Mostly kidding. But for those of you who, for whatever reason <laugh> can’t pair every second of the day when you’re trying to learn a new code base, maybe, you’re just starting an open source or maybe you’re just getting getting your foot in the door in a new area, it’s not comfortable for you or you’re in a different time zone or you’ve got zoom fatigue.
Shanea Leven: I wanna share some tips with you all today and kind of make sure that you all know that it does suck and it does get better <laugh>. I’ll start by telling a story. This story is about Shane <laugh> and her and her first day at Acme. And Shane is, you know, bright-eyed and she’s bushy-tailed and ready to ship some code.
Shanea Leven: She’s ready to prove herself, but like I said before much like you all probably you’ve got, she’s got to learn the code base first. So pretty soon, Shane finds out that onboarding to this legacy code base of the company that she just joined totally sucks. It’s really hard, it’s time-consuming, and Shane is personally having a really hard time. Why is it in fact that onboarding is so hard?
Shanea Leven: Well, when you are onboarding to a new code base, this is all of the things that you need to know but, you know I have this saying that every code base is like its own unique plate of spaghetti. It’s not exactly the same every single time. But in general, some tips to follow should get you started. Tips are broken down into three major parts.
Shanea Leven: First, you need to know the code or the system. You need to understand how to work with work with the code or work with the team. And then finally, how do you just be a human? What is the reality of being a human being and how that affects your day-to-day life and engineer? First, you need to understand when you’re onboarding to a new company’s system you need to understand the code of the system.
Shanea Leven: You need to understand how actually the code is connected. What are all the execution paths? What are all the function calls? What other functions called other functions? What are the actual details? What is the high level architecture? What are all of the domain objects? What are all of the nitty gritty details when it comes to working with the team? You need to know what is the code review process?
Shanea Leven: What’s all the design patterns? What are all the testing patterns? What are all of those gotchas in the code? The things that you just kind of hold in your head or the team holds in their head, and it’s not really written down. What are all of the deployment procedures? And finally, you need to know and deeply kind of understand just the reality of being human.
Shanea Leven: As developers, our main goal is to shift things. It’s to write code <laugh>. It’s not meant to write everything down. And so when you don’t write all of these things down, when your team doesn’t write all of these things down it gets out of date and it’s very, very hard for you to understand. And many times that information is not in the code. Repetition and retention. Turns out that when you join a new company you’re trying to onboard to a code base for the first time, or you have a new team member who’s trying to do the same you’re only gonna retain about 30% of what you’re told in your first week.
Shanea Leven: Even though you know you’re likely going to really need to understand, or you someone told you, or you told your team member, you’re likely gonna need to tell them again. Turns out it’s really, really hard to learn code. The turns out that the way that we learn code hasn’t changed in about 50 years. The process of reading code and understanding in and of itself is insufficient. We read code one line at a time, and we imagine how our systems work. That’s what we do. That’s just how it has always been. There’s very little to help us make sense of the code. And the data could be abstracted with types, it can be completely missing if you’re writing, if your company happens to use an un typed language. And reading is actually the most manual way to extract information out of code.
Shanea Leven: Therefore, reading and understanding code then takes at least 60% of our time and effort, you know, everywhere from between like onboarding as we mentioned. But then you have to read in deep dive when you’re debugging, when you’re doing code reviews or when you’re doing future work. And then at the same time, we’ve got these huge, huge systems. Like we actually have 10 times more code than we’ve ever had. And those systems are constantly changing.
Shanea Leven: While you are trying to understand the code, your teammates are shipping code like at the exact same time. It’s literally changing from under you. No wonder that Shane, and probably, you all when you’re joining a new company is gonna have a hard time <laugh>. But that experience, your sucky experience, is literally about to get worse. Because onboarding unfortunately isn’t a single point in time, it’s constant, it’s constantly onboarding to new things. Here are a few examples.
Shanea Leven: During Shane’s onboarding, Tommy over here ships a new feature. And that feature needs to get integrated with Shane’s feature. Guess what? She needs to onboard to it. Then, you know, after a couple weeks, she gets added to an on-call rotation. And then at the middle of the night, your system goes down and surprise <laugh> when you are, are in the middle of the night and the system goes down. This is not a normal part of your area typically. You’re onboarding again, you’re just doing it at two in the morning. The only option at that point is to just figure it out when people leave. Because we are constantly always visualizing everything in our heads, those mental models that we keep go out the door when people leave, whether that person is leaving voluntarily or unfortunately in today’s market involuntarily.
Shanea Leven: They were typically the only ones who kind of knew how that cool widget feature thing worked. And there’s no documentation at all. And now it’s your problem <laugh>. You’re just onboarding again. In another case, restructuring you know, teams get moved around. An individual person, the flip side of that could get promoted. Like your org might be restructured and then therefore your team’s responsibilities have changed. You’re onboarding again. And in the promoted case, it depending on like how fast that team ships code, the person’s knowledge is actually gonna get outta date really, really quickly as they are trying to onboard to their new responsibilities. In fact, you’re just kind of stuck onboarding. Again big refactors, many people don’t know this or consider this, but when you’re trying to complete like a big refactor project, it’s just actually one big onboarding.
Shanea Leven: For instance, when you’re trying to refactor a monolith into microservices, you’re trying to like break things down, or you’re trying to, you know, go back from a microservices to a monolith or, you know, some gradation of service microservice, not so micro services. In between all of those things, you need to really deeply understand how all of the variations work, what are act, what’s actually kind of helping or happening under, under the hood. And so you need to actually onboard to the whole code base so that you can make sure that you know how all of the parts are involved and how they’re connected so that you can ensure that everything gets into the new system without breaking. And then finally every single time you do a code review when you’re working on your new team is like its own little mini onboarding experience.
Shanea Leven: Essentially you need to like read the code in your head. You’re trying to remember the related code and imagine how it all works together. And that’s just another mini onboarding. And then you are just taking that code and kind of blowing it out to years and years and years of legacy code, people coming in and out, maybe acquisitions, maybe someone completed that half refactor and there’s a bunch of teched. You’re just kind of constantly onboarding. You’re probably wondering at this point, Shanea, I thought you said that you would help <laugh>, so I’m gonna help you with some tips now.
Shanea Leven: Here’s what you can do to not have that sucky experience as much as you can. It’s broken up again into three parts. Advice for the team, advice for the onboarding, and advice for continuous onboarding. Again, advice is in general and there are always exceptions. You know, some people thrive where some other people struggle.
Shanea Leven: Advice for the team in general – Start small in scope and expand strategically. you wanna provide some small early wins. Choose some tasks that help your teammate build confidence and help you build confidence trying to require learning as few new things as possible for each task. Make sure that if you’re on the flip side, that you are trying to ask for, you know, compact things and make sure that you write things down. There’s actually a lot to learn when you’re learning simple things. It’s typically more than you realize.
Shanea Leven: Problem solving in a new code base is actually really tricky, and it’s sometimes really hard to feel confident that you’ve considered all of the edge cases. So goal is to have, you know, build your confidence as part of the new team. You can start them out in a small part of the code base as possible, learn all of the relevant pieces without getting overwhelmed. You don’t wanna start your new onboarding and a huge challenge that people have been avoiding. You can ask a lot of questions if to make sure that you are not falling into one of those cases as well, but also try not to stay on super tiny things for long. You wanna start small but build consistently. Whoops.
Shanea Leven: I like to have the first task to be updating the docs for something. There’s a lot of little details that you can use to familiarize yourself with just by creating the code review, filling out the code review template, getting it approved and merging it. You don’t have to worry about having to get feedback on your code. Also, correct anything that wasn’t right in the repo setup instructions or write them up if you know they don’t exist is another great way. You can write up a small and commit a small personal bio to the repo with maybe time zones, communication preferences like Slack or email technical experience or fun facts. It can be really helpful on our remote team and, you know, be creative to try to get through the whole process, see that whole process, get that out of the way, and then you can focus on your code.
Shanea Leven: Once you’re ready to get into the code, make sure that you don’t need to understand all of the details about how the entire system works to get the task done. That helps you to build confidence that you did it right in the first place. You can gain a bit of confidence just by be feeling like you’re an expert in some small piece. And then growing out from there, so few examples, a bug fix in an area that’s well tested a small team task that other folks know how to solve, but just haven’t gotten around to yet. You can walk through the code that they’re gonna touch and some of the patterns to use to change it. So all that you really need to do is get familiar, write the code and not have, actually have to figure out how to solve anything.
Shanea Leven: Another example might be a very isolated feature with minimal risk of breaking anything. Like change a button on a link or have an endpoint return. One more attribute. Tech desk tech debt is really great. Early task, even, you know, some tedious things like upgrades or maintenance. As a new team member, you can feel like you accomplished something good and you’ve learned something and the team will really appreciate you for it. And then this is key. You wanna let each task kind of grow from there. Maybe more tasks in small tasks in new areas, but ideally, you know, slightly larger tasks in the same area. Again, your real job here is to help them feel or help yourself feel confident like you’re an expert in that area. And as soon as you can be kind of the go-to person the better.
Shanea Leven: Advice for you as the onboarding again. You’re wanting to look for a few specific things to kind of wrap your head around the code base when you’re thinking about the code and the system and how it works. So you wanna know what are the domain objects? What are the users in your system? What are the key flows?
Shanea Leven: Couple of examples might be you know, if you’re in an e-commerce platform, that might be understanding where, what, how do you define a product? How do you define the shopping cart? What’s the flow from pricing or discounts or adding something to the cart? In dev tools, it might be how do you define a code base? What is a dependency or a commit or a pull request in ed tech that might be, you know, an assignment or activity or a lesson or a grade.
Shanea Leven: And some user examples in your system for e-commerce might be like a customer or a seller. And in dev tools, it might be a developer or team lead. And in ed tech, it might be teacher or student. And then you wanna make sure that you understand the key flows. Key flows in e-com might be, you know, customer makes a purchase. What are all of those steps that they go through in the system? Seller lists the product. What happens in your architecture in dev tools, it might be, developer creates a new commit, what actually happens or system analyzes the code base, like what triggers what or what calls what, how do you understand those details? And in ed tech, it might be something similar like teacher creates an assignment or student answers a question. It might seem silly, but these are really good things to just get down and get a full end-to-end understanding of.
Shanea Leven: Some best practices you want to ask and be comfortable asking. Lots of people will know some of these things, but it’s better ask in the first couple weeks. Don’t be afraid and constantly ask questions because it will help you make your lives a lot easier. Exploring the marketing site might be a great way to kind of wrap your head around stuff. Oops. reading the docs. You might want to, whether that’s like user docs or dev docs, but you don’t wanna a hundred percent trust the docs. <Laugh> You wanna read to kind of get a big picture. But you don’t wanna necessarily a hundred percent think that every detail in the are gonna be correct. And whatever you do, please write stuff down. Draw it out so you don’t have to ask again or figure it out again. Again, you will forget 70% of the things that you learned in the first couple of weeks.
Shanea Leven: You wanna start from the key flows and then expand to the architecture. You know, make sure that you start there and maybe draw them out. What are the key components? How do they talk to each other? You wanna start piecing these things together to try to get a picture of the architecture. What are the most important components in your system? What is responsible for each of those domain objects or use cases? And how do they talk to each other?
Shanea Leven: This is an example of a monolith. Again, once you’re starting to put things together, you wanna make sure that you have an example like this that will help you to get a full picture of your system. Again, best strategies would be asking a teammate, reading the tests is a good way. Just reading the code and creating a diagram or diagramming things out yourself, and then double-checking with the team to make sure that it looks right.
Shanea Leven: Next you want to understand the low level things. What are the frameworks? Not just, you know, that your company uses React. You really want to know that they use Red React, React Router, React Query, functional components, and the React Testing Library. You want to kind of deep dive and get a detailed understanding of what are all of the underlying frameworks best strategies to kind of learn this. You wanna make sure that you at least go through some basic tutorials or guides for each framework and library. You wanna know how to use the tools that you’re using. You wanna be able to understand the coding patterns, what coding patterns are encouraged, which ones are discouraged? Every company is gonna be different.
Shanea Leven: Some best strategies to learn. This might be, you know, looking at recent code reviews to see how things are done most recently. You wanna read the code and then use a tool like GitLens to find that code review. When you’re working on a task and read to decision point, you wanna ask a teammate what that pattern likes to use before you say it’s done and ask for the code review. You want to understand the development process. Questions that you should probably look to answer might be, you know, how do we commit, how do we do a code review? How do we deploy, how do we plan a new feature? How do we give status updates and how do we retro? Next you wanna look out for code-based kind of tribal knowledge. You know, if you make a change here, you also need to make a code change over there. You don’t wanna touch this function because if you do without proper knowledge of how to do it, site performance might go down.
Shanea Leven: You wanna start to understand all of those things and look out for it. And then again, write stuff down. I’m gonna say this multiple times. It is gonna be very, very helpful for you. Don’t try to have it in your head. It will be again, cuz you’re gonna forget. Take notes. Drawing out diagrams is, like I showed before, is very, very helpful. Adding comments to the code will help everyone if they’re not there. And try to update the documentation as you go. So advice for teams. You want to make it easy to learn some of these things. If you’re on the team and you’re accepting in new teammate you want to know, have them understand what are the domain objects and the user flows and the key flows. You know, how do the key flows fits in the architecture? What are the frameworks? What are best coding patterns that we’re following and avoiding, and the development processes I mentioned. So here’s a thought.
Shanea Leven: There are lots of tools. You might be thinking, oh, there’s a tool for this, or there might be a tool for that. There’s a tool for notes. There are tools for reading code, but they’re all separate tools. And likely they’re still gonna get out of date because they aren’t connected to the main thing that you’re trying to learn, which is your code. So why should we actually have to draw out key flows by hand when the computer already knows how to run our code? Why in fact, do we have to keep reminding people about patterns and processes? You know, it’s really easy to miss stuff and we don’t on our current teams make it easy for our team members or you as the new onboarder to learn this stuff. And turns out that computers are actually much better at automating some of these things than the manual reading code line by line in our brains.
Shanea Leven: And again, every code review is a little mini onboarding experience, but our tools don’t really help us to onboard. They help us to just comment on a bunch of lines that are listed alphabetically.
Shanea Leven: For continuous onboarding, what if we could actually achieve that goal? What if all of the maps and the key flows and diagrams were all drawn out for you? What if you could just start from a file and expand until you understood the architecture? Or what if your teammates reminded you of the patterns that you should follow? Like right here, right there in your PR. What if you know every PR you could understand the impact that your code change has on the rest of the architecture? That is what we’re actually building at CodeSee. You could absolutely just use a tool like CodeSee.
Shanea Leven: There are lots of other tools as well in the code visualization space. It’s a new exciting space that’s really designed to help you feel comfortable and confident learning all of the code, even as as it’s changing out from under you. Try to invest, invest or advise your team to try to use, whether it’s CodeSee or not, some kind of tool to help you feel confident in the process. We can solve a lot of problems with having our tools help us to onboard a bit more. In conclusion, onboarding is hard. It sucks, but it can be easier. Thank you so much for listening to my talk.
Angie Chang: Thank you Shanea. That was excellent. You ran a little over, so I’m gonna have to stop us now. Thank you so much. And I know you’ll be back tomorrow with a workshop, so don’t miss out on that. It is one of the most what is it? Bookmark sessions if you look at the schedule. Amazing. We’re definitely excited. Really
Shanea Leven: Excited to see.
Angie Chang: All right, see you tomorrow.
Shanea Leven: Bye.
Like what you see here? Our mission-aligned Girl Geek X partners are hiring!
- Check out open jobs at our trusted partner companies.
- Watch all ELEVATE 2023 conference video replays!
- Does your company want to sponsor a Girl Geek Dinner? Talk to us!
