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

Jonathan Carter on September 14, 2019

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... [Read Full]
markdown guide

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


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?


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


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.
code of conduct - report abuse