Boot Up: Preparing for a Developer’s First Week

This article originally appeared on viget.com

Get new engineers on their feet with a solid technical onboarding.

You manage an engineering team that’s just hired Anya, and today is her first day. It’s a busy one for you — 1:1s, performance reviews, and a production fire to put out — but you set her up with meetings and a link to the codebase. She’s confident that she can hit the ground running.

When you check back the next day, things have…stalled. Anya had permission problems downloading the code, and then setup scripts kept failing due to a recent config change. She’s walking through the readme and figuring it out herself, but (seemingly) straightforward tasks continue to block her. By the end of the week, she’s still struggling with local issues, and your team is frequently unavailable to help. On top of her technical headaches, Anya is missing emails and meetings that no one CCed her on, which leads to more setbacks as she learns her new role.

By the end of the week, she seems deflated — Anya thought she was hired to work on cutting-edge problems for a smart company, but her discouraging first week has raised some doubts. What can you do?

We’ll fix it next time, right?

Anya will work past the roadblocks and become a valuable member of the team. The hard part is over! Why not shelve these onboarding issues for later, especially if you won’t be hiring again for a while?

Whether you know it or not, you’ve incurred costs that will last much longer than Anya’s first week. Your next engineer will start sooner than you think — you need a plan!

What does a bad onboarding cost?

• Productivity is an obvious one — you’re paying engineers to, well, engine, and the less time they spend onboarding the better. An unproductive week may seem like a small sacrifice, but as you fill more seats the penalty can skyrocket.
• Expectations for future work are set by Anya’s first steps. If your technical setup feels slow and sloppy, you can ingrain a broken windows mentality (Jeff Atwood, Coding Horror) on day one — when developers see something janky and abandoned, they might unconsciously accept it as the Official Way to build things here.
• Retention is impacted by onboarding: In one survey, 86% of respondents said they decide to stay or move on in the first six months (Credit: Aberdeen Group and @mdy). You can’t wait for developers to feel engaged and indispensable — you need them in this mindset ASAP.

• Your reputation can take a hit — a cost that’s hard to quantify but can be substantial (especially at small organizations). Anya’s peers will ask “how was your first week?”, and her response could be a big factor if they’re considering making the same move. Give her a positive story to tell.
• Group trust suffers. If Anya’s new co-workers were fine with her spending a week grinding through these blockers, what does it say about the state of the team? Building trust within a team is hard enough; it’s even harder if one member feels they’ve been left to struggle alone.

An internal branding opportunity

Organizations spend a great deal of time telling their story to customers and potential recruits, but often miss a critical audience: the people they actually hire. When the audience is addressed, it can be addressed naively. New hires frequently watch the same glowing presentations on goals, values, and history that you would show a client or investor. This narrative is easily punctured by the first-hand experience of working on your team — good onboarding requires telling a deeper and more honest story to new hires.

Piles of articles have been written on this subject, and if you’re reviewing your new hire flow, they’re worth a read.

Onboarding thoughts from elsewhere:

• Employee Onboarding at Startups Is Broken — Here’s How to Fix It
  First Round
  Great overview of onboarding difficulties, with a focus on startups.
• A Step-by-Step Guide for Onboarding New Hires
  @mdy, Startup Frontier
  Exhaustive checklist of things to consider when bringing on a new hire.
• How We Onboard New Engineers at Zapier
  Brian Cooksey, Zapier
  Zapier’s guide to onboarding engineers, with some useful examples.

This article is about technical onboarding, the piece HR doesn’t cover and that your team may not be prepared for. It might be a fraction of your overall onboarding, but you should treat it with the same care you give the rest of the experience. Start by thinking about how you would finish this sentence:

At the end of their first week, I want a new developer to think:

• “I feel comfortable contributing to the codebase.”
• “My team is committed to supporting me.”
• “I can learn what I need to flourish in this role.”
• “My work is important to the team.”
• (stretch goal) “These people aren’t crazy.”

9 questions to answer before your next hire

I don’t have a step-by-step solution to this problem; your mileage will vary depending on your team, architecture, and business. Only you can decide how best to onboard your engineers, but before you start, revisit some questions about technical onboarding:

Have I tried this myself?
Before day one, run the setup from start to finish and find out where it misbehaves. Doing this regularly prevents small mistakes from creeping in and blocking new hires. (Having a well-cared-for setup can also save you critical time later, when devs need to reset their environments or switch to new laptops.)

Do I know what access new hires need?
Not having permissions for monitoring tools, internal systems, and necessary keys is a frequent hurdle in the first week. Give new hires the same access to your systems the rest of the team has.

Is the “recommended setup” the one my team uses?
If the majority of team members have swapped out bits of the setup for their own preferences, new devs will have a hard time troubleshooting and getting help from others. Make sure that the tools you recommend are stable common denominators on the team.

Are scripted solutions clear and educational?
If you have scripts that handle the more tedious parts of setup for a new dev, good! Sometimes, these can be an opportunity for teaching — if your script just displays a spinner with “Loading awesomeness!”, you’re missing an opportunity to detail what systems are being installed, and why. Even adding “for more info about Docker, see (this link)” to the output gives valuable info to someone doing a fresh install.

Does a new hire know who to bug when they get stuck?
If not, designate a buddy. A buddy is a team member tasked with clearing new hire obstacles, and being available is their priority for the first few weeks. This is a good opportunity to give devs more mentoring practice, and to have an experienced dev around to correct the setup issues that get uncovered.

Are tests runnable, and do they pass?
The first thing a new dev should do after setup is run a test suite. This is another potential impediment for a new hire — tests can frequently be left out of the main setup, and sometimes have assertions that fail locally. Make sure setup instructions include your testing suite, and that you’ve muted noisy tests — that way, when a new hire runs them for the first time, they see your work at its best.

Are new hires getting the right communications?
Frequently, fresh team members aren’t included in existing meetings, chat rooms, or mailing lists, and miss information affects their work. Find out what your team is reading, and make sure your new hire has the same access. On the flip side, if you have noisy non-urgent emails (like monitoring alerts), give instructions for filtering or unsubscribing.

Will a new hire understand the architecture?
If you’re lucky, your systems are straightforward and incoming devs will already be familiar with the entire layout — but this probably isn’t the case. You may have multiple services, staging environments, and workflow quirks that are opaque to a brand-new team member. Give them an early opportunity to tour the system and ask questions. Architecture can be recorded as a document (and should be), but documents aren’t enough for a completely fresh developer. Schedule a meeting with a senior dev to give the overview.

Am I collecting candid feedback about the onboarding experience?
This can be tough — new hires want to be positive about their experience, but you need honesty. Acknowledge that onboarding is a work in progress (it always is!) and ask them pointed questions like “What surprised you?”, “What did you wonder about?”, and “What just plain sucked?” Sometimes this can lead to clean-up tasks that are perfect for a developer who’s still learning the codebase.

Go hire someone!

I hope these suggestions help you feel proud of your onboarding setup, and prepare your next hire for a great first day. For more ideas, check out our other Viget articles about recruiting, and let me know what you think in the comments.