Joining an existing project is daunting at the best of times. There are a lot of things to try and wrap your head around and it takes a lot of mental and emotional energy. Most human beings by nature do not like change (I’m one of them 🙂), it is uncertain and requires expending more effort than staying put does.
However, change is inevitable and positive. A new project brings new experiences and sometimes a change of scenery can bring some freshness to your daily routine.
So here are some tips that I have picked up along the way to try and help ease the transition onto an existing project.
Shout out to Jonas Meinerz for his own blog (which I highly recommend!) that inspired me to write this.
Lower your expectations and go exploring 🔎
This might sound counterintuitive but coming into a project at 100mph with expectations to have an immediate impact are probably not realistic and will likely lead to you feeling frustrated.
I understand the desire to do this and it comes from a good place of caring about what you do and wanting to help.
You may also feel like “I am being paid to be here so I need to be doing things”.
However, these expectations and pressures are often self-imposed. Ask yourself, where are these expectations and pressures coming from?
Often the answer is from your own desire to get things done or have an impact.
Instead, give yourself a buffer when joining a new project. You could call it the exploration phase, the discovery phase or the onboarding phase.
It doesn’t matter what you call it, what matters is that mentally you give yourself time to get up to speed without pressures or expectations to deliver.
Depending on the size and complexity of the project this could be weeks or even a couple months or even longer.
Remember everyone who joins the project will have to do this anyway, it just helps to set some healthier expectations for yourself and the team around you.
Be sensitive 💙
When you join a new project it can be fairly common to immediately see something that the new team has done or are doing that you feel doesn’t seem right or could benefit from some significant improvement.
The likelihood is that you are correct. Your observations with a new perspective may have spotted something which the rest of the team have been doing habitually without thinking about it and you can see a clear and obvious approach to improve this for everyone.
But before you jump in and start suggesting changes, just take a moment to be sensitive.
Every project and process has its idiosyncrasies and some have a context behind them that explains how they ended up this way.
Moreover, some people may have spent a lot of time honing these processes or code structures, so be sensitive to the possibility that critiquing something might also be viewed as critiquing someone.
Onboarding Checklist ✅
This is it! Your first day on the project and you arrive at the daily sync (on time, because it’s your first day).
There is a tendency to feel a bit out of things when everyone is going through their cards or tasks for the day and everyone seems to have a clear idea of what they are doing.
You also want to feel part of it and want to have something concrete to say in the sync.
A quick way to be able to do this is to create a task for onboarding and add an onboarding checklist to it. The team you are joining may already have an onboarding checklist for onboarding new people anyway, but why not create a card for it and add some of your own things that you like to do for onboarding as well (dare I say, you may even add some things from this list 😉).
Business Overview 💰
Sometimes we forget that behind the codebase there is often a business.
In fact sometimes the hardest thing about joining a new project is getting up to speed with all the domain knowledge.
Consider asking someone from the business side of things (preferably not another developer) if you can schedule a call just to have a chat about how the business works.
This will not only give you invaluable information about what you are working with but you will also discover what are the best channels of communication to get hold of stakeholders.
Technical Architecture Overview 🎛
So far we still have not looked at anything technological, but let’s do that, without heading into the codebase just yet.
Ask one of the developers or someone from the DevOps team (if there is one) for a chat to go through the technical architecture.
Often you will find that understanding the technical architecture can help to answer a lot of questions that you would encounter in the codebase anyway.
For example:
- How many databases are there?
- What type of database are we using?
- How many front-end clients interact with our server?
- Is this a monolith or micro-services?
- Is there an API?
- Do we integrate with 3rd party API’s?
- What technologies are we using?
- How many environments are there besides production?
- Which branch deploys to which environment?
You will be surprised how many things you will discover about a project by gaining an understanding of the overall architecture and at some point you will likely run into issues with deployments or certain bugs that require knowledge of this anyway.
UI Walkthrough 🖥
This may seem more obvious, but why not book in a chat with someone from QA or a developer to walk through the UI.
Often it will be too vast to walkthrough all of it, so I find it helpful to ask to walkthrough the part of the UI that you will likely interact with most in your work. Go through some happy paths just to get a brief overview and you will pick the rest up as and when you encounter those areas.
The UI may also reveal helpful implementation details such as single page application functionality.
Codebase Walkthrough 👨💻
I have actually rarely seen this done, but a senior developer on a project I joined recently did this with me and I found it really helpful.
The idea is not to go into detail and look at individual lines of code or do any deep dives, you can do that when you get a task in that specific area. The main purpose is to get a high level overview of where certain parts of the code live. Focus more on folders and files rather than what is in those files.
It can be as simple as where assets are stored or where the JS files are kept. But often it will actually expose certain design patterns that are used in the
codebase and this is a good springboard for asking questions about certain styles within the code.
Pull down the repo and get it running locally 💻
Finally!
Something I never do, but I should, is actually read the ReadMe!
So often I just jump into trying to get the project set up that I overlook something as simple as reading the ReadMe. I then
ask questions only to be sheepishly redirected back to the ReadMe. Hopefully it is up to date and will help you get the project set up locally.
But if there is something not up to date, make a note of it, even something as simple as typo. Remember this because we will use it to our advantage later.
Generate an ERD diagram 📈
If like me, you are a visual learner, I find this to be a neat trick to help you to get up to speed with the database quickly, without having to trawl through the
schema.
There are different tools out there that can do this for you, but if you are using Rails there is a great gem called rails-erd that
you can use.
This can help you to also understand the size of the system you are working with, how many data points there are, and if there is a big table you need to watch out for.
Lets ship a thing 🚢
Remember that typo we spoke about earlier, let’s use that to our advantage.
You might not be ready to commit any working code to the project yet but you might be able to improve some documentation somewhere that lives inside the repo after your own onboarding experience.
Create a card for this change like you would for any coding task. Treat it exactly the same as you would any coding task even if it is only a minor correction.
You might feel like this is overkill, but this is a really good way to learn the workflow of making a change on a feature branch and deploying that change through the different environments all the way to production with minimal risk. You will also see how you move the card along on whichever task planner tool you use.
You will get to learn and ask questions about the end-to-end process from development all the way to production in a relatively safe environment. This will lessen the information load when you come to work on your first code-based task and allow you to focus on the code itself without having to also learn the process at the same time.
Ask for easy tasks/cards 😃
Yep that’s right, explicitly ask for easy tasks!
We already set expectations when we spoke to the client about the discovery phase, so lets use that time to do some discovering.
The purpose of asking for easy tasks is not to give you an easy time (even though by now you deserve one!). The purpose is also not to be able to ship things quickly. Everyone knows you could change the wording of a button quickly.
The purpose of an easy task is to give you time to look at that area of the codebase and learn some things about it. Removing complexity from the task itself allows you to focus and work through the complexity of the codebase whilst feeling slightly more comfortable about being able to make a rather trivial change.
You will likely encounter some design patterns and get a feel for some of the automated tests that might be used, as well as linting, and hopefully it will be a springboard for pairing with other developers as well.
Pair with other developers 🍐
Developers who have been on the project for a while will likely have a lot of domain knowledge and experience so why not leverage that to your advantage.
One of the ways of doing this that I find most helpful is to ask to pair with another developer on one of their tasks from beginning to end. Sometimes jumping into pairing with another developer whilst they are in the middle of a task can be harder to acclimatise to.
The other advantage of starting pairing from the beginning is that you get to see how this developer does everything. Pairing is about more than just seeing the code that is written. You want to see how this developer prepares for tasks on this project, what external tools they might use and how they manage the admin side of a task, such as using planning tools.
Ask any question ❓
Lastly, ask, ask and ask some more.
It can feel embarrassing sometimes to feel like you are asking so many questions and even vulnerable to be showing others that you know very little.
But at some point on this project everyone knew nothing. Everyone asked the most simple questions because no one was born with the divine knowledge of how these things worked or came to be.
So allow yourself to be human and ask away.
I hope you find some of these tips useful.
It goes without saying that everyone onboards in different ways and ultimately everyone should onboard in a way that feels most comfortable and natural to them. There is no one size that fits all.
But maybe you can add one of these tips to your onboarding arsenal for the next time you join an existing project.
Thanks for reading! ✌️