loading...

What are the biggest challenges when onboarding and contributing to a new codebase/project?

lostintangent profile image Jonathan Carter ・1 min read

Hey All!

In your experience, what have been some of the biggest challenges you (or others on your team) have faced when getting setup and familiar with a new codebase, and then ultimately, merging in your first change? For example:

  • Setting up your machine with the right SDKs to build/run the app (e.g. specific version of Node/Java)?

  • Knowing which IDE and extensions are needed in order to productively work on the app?

  • Configuring access to private repositories, package managers or registries?

  • Setting up the needed service dependencies for the app (e.g. a database)?

  • Actually getting familiar with the codebase itself? (e.g. it’s directory organization, any specific style conventions)

  • Understanding architectural decisions that have been made, and how to best apply those for future work?

  • Learning the team processes for how to handle commits/PRs (e.g. thoughts on rebasing, do we use conventional commits?)

  • Determining who to ask questions about specific parts of the codebase?

  • Something else?

Many of these have potential solutions, and so I’d love to hear not only what challenges you’ve faced, but also, how you’ve worked around them. In general,
I’m just very curious to hear how teams are able to improve the onboarding and contribution process for new members. Thanks!

Discussion

pic
Editor guide
Collapse
bananabrann profile image
Lee

For me, it's the lingo and acronyms. I'd say about half my time at work is deciphering lingo used in various documents handed down to me from non-tech higher-ups, just to discover it's far too abstract to work off of

Collapse
lostintangent profile image
Jonathan Carter Author

Yeah that’s a good point! Within MS, we have way too many acronyms and code names, and it’s take a bit for new members to get up to speed :/ How do you end up working around this? Just asking what terms mean one-by-one?

Collapse
bananabrann profile image
Lee

The "new guy" on our team is the entire team. We ask for further explanation of what is to be built, and the documents we're given are riddled with corporate jargon that abstracts the objective so far away that we effectively don't know what to code.

The way we've started tackling this project is to rapidly pump out small versions. Everyday something is sent to higher-ups for feedback. We use that daily feedback to slowly, slowly refine what we're suppose to build

Collapse
sarafian profile image
Alex Sarafian

Most of the issues can be solved if the repository contains scripts and information on you to onboard a person or a new development environment. I used to work somewhere where all you describe took at least 1m onboarding. With scripting that helped drive our CI and CD pipelines, this process was reduced to 1d.

The biggest gap is in my opinion the historical context.This is something that even when a proper wiki is used it is difficult to understand especially when people have move out.

The most annoying is the acronyms and lingo. This also depends on quality of collaboration and culture. Some cultures think that converting all verbal and written communication to acronym based it helps accelerate the discussion where instead it only creates more confusion and less quality thus reducing the speed at the end. It also makes some people feel important. Lingo will always happen but when new people are in the discussion it should be limited. Usually when there is no change it means two things:

  • Onboarding process is of no importance to the organization
  • New people join the discussion too rarely and probably that means the team is mentally entrenched.