Ask HN: What is the most effective way to onboard an engineer?

Having a document on how to pull source, build it and deploy it in a development environment

Have a bug to fix for them

A starter project which involves using the codebase in an interesting / different way.

I plan on spending the full day with the new hire or intern, and my goal is to go from 0 to a running build to a commit in day 1. Sure, it is kinda a hassle for me to block out the whole day, but that gets them past all of the poorly written docs and stupid install/setup bugs. They get excited instead of frustrated. The rest of the first week is exploratory- I ask them to make improvements to the docs based on their experience (get them up to date if they're behind), and also to share notes on larger improvements or ideas they have while they are still fresh. I aim for 1 commit a day in different parts of the codebase to give them some breadth. The second week I treat them like a normal team member to start building a regular flow, but give them a light week of work and block out ~1 hour a day for code reviews and Q&A.

Everything kinda sucks at startups, especially docs. The right way to do this is invest your time up front in order to save you and the new hire time in the long run.

Mentoring doesn't mean do the work for them, so first thing you may want to do is provide the new hire with the minimum knowledge to setup a local dev environment and navigate the codebase.

For a new hire I also made one slide with a diagram to explain how to go from 0 to production, this gave him a high level overview of the whole system.

Try to make them push something on the first week is very important, the sooner they finish their first ticket the sooner they do the 2nd, 3rd and can repeat and familiarise with the development process.

Finally ask new hires to document what they are learning or improve existing docs – a fresh pair of eyes/mind is priceless.

With time your poorly documented system will be very onboard-friendly.

Things which I've followed and would recommend:

- Have a vagrant box set up so that the new engineer doesn't have to waste his/her time setting up the system. Use Ansible/Chef/puppet for provisioning the vagrant box. Saves at least a day.

- Make sure all the git repos have a good README file explaining the project details.

- If you have an API powering your backend, use http://swagger.io/ or something similar, so that other engineers don't have to waste time explaining all the API endpoints.

- Maintain an internal wiki or a Google Sites which lists all the common problems faced earlier. You can also explain the business logic and the general flow of the application here.