DEV Community

Hesam Seyf
Hesam Seyf

Posted on

1

How to Effectively Onboard New Developers: Tips for Team Leads

A team lead is onboarding a new developer in a traditional way.

This post is a copy of my original medium article: https://medium.com/@hesam.seyf/how-to-effectively-onboard-new-developers-tips-for-team-leads-a60429fe0d3c

Have you ever had a new member in your team and you had to teach him everything about your project and the business you’re involved? What challenges did you face? How did you tackle them?

I’m the lead front-end developer in our company, and I want to share my experience and tips for onboarding new members.

The Ostrich Scenario

Here is an example scenario when you do not have any plans for your new colleague:
He clones the repository, runs npm install, goes to the package.json and takes a look, finds a start script in it, and runs it. And…… BANG!!!
He faces a huge error on his screen that could happen for various reasons. He asks you to help him. So, you leave your current task and help him and get back to your previous work. A few moments later, he faces another error while trying to run the tests. Again, he asks you to help him, and so on.

This ping-pong could last at least a week(I’ve seen worse, believe me!). During this week you spent half of your time helping the newcomer, apart from the time consumed for context switching. Both of you feel discomfort and embarrassment because he thinks he knows nothing and you feel your project is not clean enough to welcome the new members. Here are a few tips that can help you overcome this challenge.

Document Everything

The silver bullet for facing such challenges is “documentation”. You need to write down everything related to the project, your business, and your company. You may need more than one document to share all the required stuff. Of course, It is vital to write a “good” document.

What is a good document?

The answer depends on which type of documentation you are trying to write and who wants to read it. In this case, here are some tips for writing a good document:

  • Friendly tune: Remember that your audience is a new member, and he may feel some insecurities and discomforts for various reasons. After all, joining a new team could also be challenging for him. So, having a friendly accent rather than a formal tune is important. This helps him to feel more comfortable with his new team.
  • Keep technical documents near the code: Developers love IDEs. They would be satisfied if everything ran inside their IDE. It is common to keep technical documents such as development prerequisites in the repository. Markdown is the best format for such stuff. Always have a fluent-tune README.md file in the root of your repository. Avoid keeping the default README file that is auto-generated by the framework you are using.
  • Put some multimedia: Reading can sometimes be boring. So, add some video documents to facilitate this process. Capturing video docs can be time-consuming and hard to change. For this reason, it is important to turn those documents into videos that are less likely to change in the future, such as business documents.
  • Have a document for documents: To organize your documents, It is a good practice to create a document that links to your other documents.

Business documentation

You need a document that describes your entire business. What is your business about? What problem does it solve? Who are your industry competitors? These questions could help new members have a brief understanding of your business and avoid ambiguities and misconceptions.

Process documentation

It is important to describe your company rules, culture, workflows, and methodologies. If you are in a medium-sized or large company with an HR department, it is the HR department's responsibility to write such documents. But if you are in a startup or small company, the responsibility is yours.

Technical documentation

As I mentioned, these types of docs should be pushed into the repository and the preferred format is markdown. You need to specify exactly how to develop conveniently in the project. Here are a few of the items that should be mentioned in the technical document:

  • The development prerequisites and how to fulfill them, such as the Python version you’re using, the environment variables required for running the project, and the packages you need to install. You can add some links to the packages and libraries that are going to be installed.
  • How to run, test, and deploy the project.
  • Your branching strategy and the convention you are using for the commit messages.
  • The entire CI/CD pipeline and the steps that should be passed before deploying into the dev/stage/prod environments.
  • Coding conventions

Validation and Retention

The best way to prove you wrote a good document, is by passing it to the newcomer, asking him to follow the instructions and notify you if there are any missing parts. After that, simply add the feedback to the document. By doing this once or twice, you can guarantee that you wrote a good document.

Documents need changing during the time. So, keeping them updated is as important as writing it. Outdated documents could lead to misconceptions and in some cases, cause more problems than having no documents. To have them updated, always review them before passing them to your colleague and update them if necessary. This simple rule grants that you always have updated documents.

Automate Tasks

Another thing that can simplify the onboarding process, is automating as many things as you can. If something is automatic, it does not raise any questions at all since its details are placed in the background and the developer would not be aware of it. Keep in mind that all of your scripts should be mentioned in the technical document. Here is a list of the things you can automate:

  • Installing prerequisite packages and setting development environment variables
  • Enforcing code conventions by adding them to your Linter rules and verifying them in your CI pipeline
  • Adding code generators for creating modules. Some repository managers(e.g. Nx) support it. In Nx for example, you can inherit its default generators and make your changes.
  • Add git pre-push hooks to enforce your commit message convention. Developers cannot push their commits unless they follow your rules.
  • Containerize your applications. Developers are comfortable working with Docker containers. In a container environment, you can bundle your application’s dependencies so it runs on any machine that has Docker installed.

Stick to the Industry Standards

Another thing that facilitates new developers to onboard into your project, is following conventions and frameworks which are well-known among the whole industry. This can boost the time consumed for the onboarding process since your colleague may already be familiar with some of them. Avoid inventing rules, conventions, or frameworks unless there are no other options (in most cases, there are). Here are some standards you can consider:

  • Follow a vast-used development methodology, such as Scrum.
  • Choose a suitable branching strategy(Git-flow, Github-flow, etc.)
  • Enforce commit messages to follow Conventional Commits.
  • Choose the right framework that is suitable for your project and avoid creating new ones. Believe me, you do not have to reinvent the wheel.

Clean Code is the bible

Sticking to the Clean Code rules and considerations introduced by Uncle Bob has a major impact on the developer’s experience, particularly on new developers. Having short functions, well-named files and variables, and a “Screaming” folder structure lead to less confusion and more comfort during the first days of joining the team. So, keep your code clean if you want to keep your team happy.

Conclusion

Onboarding new developers effectively is not just about teaching them the technical details of a project; it’s about making them feel welcomed, supported, and prepared to succeed. By writing comprehensive documentation, leveraging automation, and adhering to industry standards, you can transform onboarding from a pain point into an opportunity for growth — for both the individual and the team. A smooth onboarding process reflects the health of your project and the maturity of your team, so investing in it pays off in the long run.

What are your go-to strategies for onboarding new developers? Feel free to share them in the comments!

Image of AssemblyAI

Automatic Speech Recognition with AssemblyAI

Experience near-human accuracy, low-latency performance, and advanced Speech AI capabilities with AssemblyAI's Speech-to-Text API. Sign up today and get $50 in API credit. No credit card required.

Try the API

Top comments (1)

Collapse
 
zethix profile image
Andrey Rusev

I like documentation! :)

One suggestion - there are now tools that can help too. I do recommend Backstage very often. Might not be immediately obvious how it can help with onboarding, so a company will have to invest some time into customizing it - but I think it's worth it.

We've also developed some internal tools to help specifically with illustrating How does it work? - like a top-level overview of the internals of various components... One practice I might recommend here is to get some nice telemetry charts, particularly if you've got decent traces (or 'spans') - a few screenshots of different scenarios can go a long way in helping new members to get the whole picture, how a piece of code (covered by this span or that span) fits and so on.

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay