How to Onboard Software Engineers

Kate Heddleston is freaking awesome, if you don't know. Her talk at Pycon 2015 about diversity in engineering environments is fantastic. Well explained in language free of activist rhetoric -- it was a pragmatic and thoughtful speech. Her blog expands on much of what she covers and should be read.

On the topic of on-boarding -- super important to get right! The idea of making your people the best they can be is lost, I think, on our generation. My grandfather-in-law was a mechanical engineer at Chrysler back in the day when they had a special school they ran to train their new recruits. When he started he had no idea of how cars worked but they picked him up from school and gave him the training he needed to become an important figure in their company.

Focusing on hiring the best because hiring someone mediocre will damage your business is negative thinking that can kill your on-boarding, and thus your culture and business. I've worked at places with terrible on-boarding and it was a fight just to get some direction and support for your work. Getting the attention of management was something you wanted to avoid which led to people becoming complacent about their work and its quality.

Great article. On-boarding is important to get right.

Onboarding is a people/process/docs/technology problem. To the limited extent that it is a technology problem, you really can't go wrong with a) treating it like it is an actual shipping product of the company (implying a minimum standard of care like e.g. a repository, documentation about it, and a dedicated place to put issues) and b) actively maintaining something with the goal of getting someone up-and-running quickly.

None of my projects are at the point where you can just "vagrant up and go", but the next-best thing has been READMEs in the relevant repositories with exact lists of "Type this, type this, type this, type this. You now have a fully-working system running on localhost and you should be able to type this to get a full green test suite. If you can type this and it does not come out green, fixing that is more important than anything Patrick is doing right now."

Here's, for example, what we have for getting someone up and running on Appointment Reminder (in preparation for me soon no longer being the engineer who keeps all of that system in my head): https://gist.github.com/patio11/a0b1063c5d33b5748da6 Feel free to steal ideas in terms of level of detail or useful things to include. (A lot of the magic is in the rake commands like "setup_site", which take care of "All that crufty configuration stuff which you would otherwise need a senior engineer to do for you prior to actually seeing the page render correctly on localhost:3000.")

Quick hack which helped us on making sure this guide was actually accurate: we had two engineers coming into the project at the same time. I wrote down everything I thought they needed to know. Engineer #1 implemented to the document I had written, filled in the blank spots where he needed to ask questions, and then we committed the readme. Engineer #2 then had to do it off the readme without asking me any questions. Given that he was actually able to do this, we have high confidence that there is not at the moment anything rattling around in my head which is absolutely required to get up-and-running and documented nowhere else.

I wish everyone took onboarding seriously.

I worked for one company for a month. From the get go they had 100+ staff but no onboarding. Nobody knew how to set up the development environment or even get the application working on the company laptop. Nobody could show me how to VPN to client sites or show me how the software worked. I was meant to support it...

I was in my manager's office every day letting her know hey I really need assistance here, nobody seems to have time, nothing is working, I'm not learning anything and this needs to improve.

She'd tell staff to assist and they just wouldn't. And rinse wash repeat the next day.

A month in we are in a meeting and some difficult software issue comes up and it's assigned to me to fix. I mention that I don't have it running, don't know how to use it, have no method of finding who the customer contacts are to call them and will sound stupid not understanding anything, but also haven't been shown how to connect in. That I'm happy to shadow someone else and learn it.

It felt shameful but I knew it was the right thing, I had a year of extensive help desk experience under my belt including programming and other development, bug fixing, accounting, you name it, I was even team lead. I was used to dealing with multi million dollar clients and had no qualms about doing so... but this place was dysfunctional.

Anyway the boss stared me in the face in the meeting and called me a liar, to shut up and get to work. I was stunned. I repeated myself and she turned to my coworkers who claimed they had "showed me everything". I hadn't spent more than 5 minutes with them in the entire month and had been in her office every day. She told me to start pulling my weight and stop lying.

I walked very calmly to the office printed out a resignation and left my keys and walked out the door. I didn't get paid (a funny side effect of walking out of a job) and the move left me penniless and ALMOST homeless.

Luckily I got a job just in the nick of time shortly after, at twice the pay, and being treated like a human being. I removed that place off my resume and rarely discuss it because it's so humiliating.

I still remember the recruiter calling me screaming how unprofessional I was - he only cared about his lost bonus. I explained I was extremely professional but that after being humiliated and called a liar in a meeting and having none of the promised training, or anything remotely capable of making me a functional employee, there was no recovery.

Now I take onboarding very seriously.

I'm in the midst of being onboarded at a very large healthcare organization. In addition to the complex SOA infrastructure, we deal with a multitude of databases, accessible through many different methods, from a number of vendors. There's a ton to take in—not to mention the business complexity inherent to the organization as a whole.

Heddleston's point about having less-senior people do the mentoring is especially apt. While I've received support from everyone in the team, the most helpful person has actually been an intern with only a few years of programming experience under his belt. While I have over a decade more general programming experience than he has, he knows a lot more about the specific domain, and has been an excellent teacher. I feel that this arrangement has been beneficial for both of us—as I've gained domain knowledge, he's gained confidence and depth in his own knowledge.

I think that a big part of this is not setting expectations too high—no matter how senior the new employee is. While I have a fair amount of experience, the expectation in my new position—both from me and from the team—is that it will take me a while to get up to speed,(especially given the complexity inherent to the role), even though I'm not coming in as a junior dev. Therefore, I don't feel the need to pretend that I'm an expert in something that I'm not, and there's no ego hit when I'm being mentored by someone who is technically my junior.

In my city, it seems like most everyone is looking for senior devs—to the point that they leave positions unfilled for months rather than hiring someone they don't consider senior enough. This is madness, and damaging to the industry as a whole. We need to focus more on efficiently developing talent, and Heddleston seems to have some great ideas for doing so.

I think outside of the day-to-day (you need to know Python, here's how to get Vagrant running, this is how you submit a code review) there can also be a gap in cultural onboarding. For example, someone moving from a large tech company to a startup has certain norms and expectations that they may slowly re-evaluate (if they actually do) over a number of weeks or months, potentially harming the product and even their own career -- for example, "that's not in my job description" doesn't fly at a startup but can be a protective reflex at a large company. (One may argue someone with this attitude may not be hired at a startup in the first place, but sometimes the attitudes and expectations aren't so upfront and clear-cut, and are hard to test for at interview!)

Would love to find some examples of great cultural onboarding where it's not just the "what" of the work that a new hire learns, but also the why and how, to avoid implicit assumptions and biases from day one...

I ran twitter's new engineer training for a long time, and much of this rings pretty true to me. I would only add 3 things: -1 the skill of teaching is approximately orthogonal to domain knowledge, and the difference between a decent and very good teacher is huge, both in terms of student-reported happiness and in terms of retention of the material covered. -2 history with the company tends to be very valuable, in that new hires are often curious about _why_ the company decided to build system X as it was. My goal was that teachers should be able to answer most such questions accurately, and truthfully say that they didn't know in the other cases. I found (anecdotally, because this data is hard to capture) that the student-reported quality of a class was generally proportional to the maximum length of question/answer/followup q/answer/... chains. -3 the onboarding process is an extremely powerful propaganda platform. During twitter's long transition from ruby to scala, (before I ran it) there were a series of presentations that were forward looking to the point of inaccuracy: they described as existing in the present that which we hoped would one day exist. This confused a bunch of new engineers when the rainbow unicorn scala world promised them did not materialize. On the positive side, many of them were then motivated to help build a scala world.

Somewhat OT, but maybe related.

Does anyone actually work as a QA for documentation? I've been in many projects where "just read the docs" or "go read this doc", and... nearly always it's out of date, or missing key information (like who wrote it, who to contact for access to systems in the document, etc) or so scantily written as to be useless.

Saying "I wrote docs" but having them be abysmal seems to be the norm. People now accept that having unit tests for code is a thing (not always done, but at least a thing) - is there an equivalent for documentation?

great point about onboarding providing a high ROI, it's something I haven't thought enough about. this is a particularly useful part: "The best person to help someone set up their development environment is the last person who joined, regardless of seniority."

An inability to bring on new talent, junior or otherwise, is a symptom of lacking essential documentation. If I can't come into your office and have a copy of your software running or successfully compiling on my machine in less than an hour, something is very wrong with your documentation, tooling, or (lack of) build process.

"Here's Jim. He's our Widgitsoft guy. He's the only one who works on Widgitsoft. The system is entirely undocumented because Jim knows everything. Yeah, development has been slower than expected lately. Yeah, it would be nice if we could bring on a contractor when necessary, but getting to that point would be a lot of work, and we'll always have Jim."

This is timely, as I’ve just gone through the worst onboarding I've ever experienced. It took two very long days to install an OS on a machine and get it to boot (I had to assembly my computer and then use the corporate installer, which failed multiple times with errors like “an unknown error occurred”). It then took me about a week to run the local project’s “hello world” (I was initially pointed to documentation that had been deprecated for months, and then when I found the right documentation it was incomplete and out of date). The actual process to get there was hilariously baroque; for example (if my email records are correct and I didn’t get duplicate emails from the system), I must have clicked through 18 EULAs to get a subset of the permissions I need. I promise, that’s worse than it sounds since the form to do so took more time to click through than you can imagine. It was a month before I could effectively do any work at all.

I originally thought that I was just unlucky, but when I asked around I found that I had an above average experience, at least among people near me who started recently. Unlike many other folks, I was actually able to get a username/alias, a computer, and an office. I don’t know what folks without a username do since they can’t even start clicking through the necessary EULAs to get permissions to do stuff, let alone do any actual work.

I’m not sure how it is in other parts of the company, but if you imagine that it’s similar and do some back of the envelope math on how many people get onboarded and how much losing a month (or more) of time costs, it comes out to N million dollars for a non-trivial N. And that’s just the direct cost of the really trivial stuff. It’s hard to calculate the cost of the higher level stuff that’s mentioned in the article, but I suspect that’s even more expensive.

Standout quote: "People think that confidence follows skills, but it’s usually the other way around where skills follow confidence." This is a fact that really needs to be more widely acknowledged. (It also casts the microagressions that have the effect of chipping away at the confidence of women and minorities in a rather uncomfortable light.)

I really like this article.

I've been learning to interviewing potential hires. One of the questions I ask is, "Do you have any questions for us?" The questions can tell a lot about the prospective hire.

Turn this around: "What is your onboarding process?" is a great question from prospective hires.

This past year, having taken a number of short-term contracts at small teams, I've learned the hard way how to survive getting thrown into the deep end. You have to get really aggressive about communication, especially on a remote team. A lot of expectations can get lost. It's possible to survive and thrive without a good on-boarding process, but you have to step up and assume that responsibility yourself.

This isn't everyone's thing, and often feels like straying into rude, invasive behavior -- and from the startup's perspective, you lose a lot of great people too -- so asking this question will give the prospective hire an idea of whether they are getting set up for failure. Even an honest answer from the potential employer, "We don't have one, we are very busy and everything is really chaotic here" will tell you a lot about expectations (for both parties) within the first couple weeks of starting work.

And obviously, if the potential employer gives some BS in lieu of a straight answer, why waste time joining?

I think lack of onboarding is probably one of the biggest problems with open source projects as well. You can't expect to get new contributors, if you have no documentation on how to setup a development environment, which tools you use and how the project is structured.

On this subject, 10% of Airbnb engineers started last week: https://twitter.com/mikecurtis/status/633759315480805376

Kind of crazy...

The form of the interview was a bit weird: All the questions seemed to be entirely predetermined, with no follow-up questions and no opportunity for the answers to guide the direction of the interview. But on the other hand they were open-ended enough that it was more like a talk where the interview questions were hardly needed – essentially:

  So I heard you like x.
  How did you get started with x?
  Tell us a few things about x.
  In addition to those things, could you tell us something more about x?
  Is there anything else you want to say about x?

But very interesting nevertheless! :)

I really enjoyed this video as I am currently looking for programmers and coders. I am leaning towards female engineers as I am a proponent of diversity and that I want to produce gender neutral software for my market. My goal is to hire the "right" people who can objectively work together while also producing software that takes multiple points of view into its development.

I don't agree with all the advice, but I do think it's a good message. My favorite part is actually on pre-onboarding: "If everyone has to come in and manually set up everything, what you have is this super painful onboarding process that’s just going to bottleneck your company."

My Induction at my first job after being issued with my labcoat was an hours instruction on how to boot the PDP11/40 and I was told ah the company library has a book on FORTRAN go and learn it :-)

I wish the article would start by explaining what the hell "onboarding" is, since I've never heard that word before...

Great discussion. I actually didn't know fog had a large blog section with podcasts/videos. Will be listening to these now :)

I really, really like this post. It applies to us product management dweebs too.