First steps after joining a project

I’m a freelance contractor, and I change projects rather often. I noticed that how the beginning of my involvement starts has a big impact on the whole engagement.

Part of that is just being able to contribute early and use the grace period (nobody’s surprised if you ask “stupid” questions while you’re still onboarding), and part is the attitude you build and the impression you make. If I start well, It’s easy to continue well.

I learned not to rely on onboarding led entirely by the welcoming team members; they are always well-meaning, but there are too many things that are in the “elusive obvious” area for them; they won’t mention some things because they aren’t even aware that they know them. Here I’m attempting to address mostly these aspects; I’m not mentioning things that are impossible to overlook, like “How do I run the project?” or “What tools do we use?”.

There are three main areas I need to learn about when joining a project: people, product, and code.


It’s important to understand the politics of the project to be effective. You need to know how decisions are made. Regardless of the official org-chart, some people are more influential than you would guess at first. Teams also differ in how “democratic” or “authoritarian” the decision process is.

Some questions to ask yourself are:

  • Is there somebody “dominating” the team regarding opinions or decision power?
  • If you want to introduce changes to how the team operates, who exactly do you need to convince?
  • Does the team even have a say in important decisions, or are they always coming from above?
  • Do decision-makers rely on intuition alone or also on data? If on data, how careful are they in analysis? Often managers are very selective about looking only at data that supports what they already believe.
  • Is anybody a contrarian that responds with criticism to every proposal or idea? On the one hand, people like that might be a bit hard to work with, but on the other, they can help you make a convincing point that everybody else will agree with (at least that’s what I like to think; I’m probably such a person).

It’s immensely useful to understand people’s cultural backgrounds. People from different parts of the world tend to have different attitudes when giving and receiving feedback, agreeing and disagreeing, or being implicit or explicit about the context. Read The Culture Map for more about that.


The challenge here is to get a big picture; product managers and other team members tend to be so deeply submerged in details that they might fail to convey the high-level information.

Questions to ask here are:

  • Who exactly is using the software? What are users’ expectations around performance, reliability, and accessibility?
  • How exactly is the product making money or otherwise contributing to the company’s goals?
  • What features are the most complex and problematic?


The first thing I do after cloning a repository is to run git-churn. It shows which files have been touched by the biggest number of commits, and it’s a pretty good indicator of where the complexity lies within the project.

It might also be useful to run git shortlog -sn to see the commit count per author to have some idea about who is likely to be most knowledgeable about the repository.

In some teams, individual members specialize in particular parts of the codebase. You need to ask them about it and note it down so that you know who to ask for help when relevant.

Of course, some projects are more unusual than others, and from time to time, something will really surprise me; however, I found that getting answers to questions I mentioned let me get from clueless to quite effective pretty quickly.