
How to Onboard Software Engineers - GarethX
http://blog.fogcreek.com/how-to-onboard-software-engineers-interview-with-kate-heddleston/
======
agentultra
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.

~~~
sjcrank
Regarding the negative thinking, this is a really important point. Consider
these two alternative attitudes when on-boarding a new employee:

1\. Let's evaluate to see whether the new developer is good enough, so we can
fire fast if our expectations are not met.

2\. Let's figure out how to help this developer achieve his/her maximum
potential for adding value to the organization. If for some reason the
developer is unwilling or unable to develop to a level that makes a positive
contribution, then we consider separating.

I find the second approach much healthier for the employee and the
organization.

~~~
devonkim
False dichotomy in my world since I employ both 1 and 2 with a very, very
lenient set of guidelines for 1. Some things do not manifest in an interview,
and that's where during the first couple weeks I check for some basic
professionalism. Things like: 1\. Are you responsive to e-mails or IMs at all?
I don't mean are you answering e-mails constantly and within 10 minutes each
time, I mean "do you answer e-mails when you are asked for a response?" 2\. Do
you ask questions at all? If it's day 7 and you still don't have access to
Github because you never asked "So where do I, you know... push code?" I have
to wonder what you were doing from days 1 to 6. 3\. Have you confirmed what
your expectations are if they are not clear to you? I give a basic 1-day
project fully expecting it to take a bit longer, but if it takes a whole week
and you're silent, I have to ask why you think it's ok that you have no idea
what's going on and that it's ok. If I suspect they're not pulling their
weight, I'll give a project where they will immediately be blocked and require
assistance if they spend more than 10 minutes investigating the issue. This
also helps me determine if someone is simply really, really shy or if they're
just not doing any work.

And lastly, reaffirm that you've done 1 to 3 and communicate clearly that
those are the expectations before you fire the person for being pretty much
dead weight.

You can't figure out how a lot of people will work until they actually start a
job.

------
patio11
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](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.

~~~
nemild
To make app setup even easier, you can write out scripts that bootstrap the
application:

[http://githubengineering.com/scripts-to-rule-them-
all/](http://githubengineering.com/scripts-to-rule-them-all/)

~~~
mseebach
Scripts like that need to be able to recover from a very wide range of error
modes caused by subtle differences in how target machines are setup - or at
least fail in a reasonably obvious way.

Writing such a script is significantly more time consuming than writing a
README, and for it to be worth the effort, it should be expected to save a
fairly high multiple of the time it takes to write, debug and support. For
GitHub, that multiple is definitely very high, for Patrick, it might not even
be greater than one. YMMV.

------
sqldba
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.

~~~
afarrell
> I didn't get paid

Wait, you didn't get paid for the time you had been their? I'm pretty sure
that is a violation of labor law, at least in any state in the US.

~~~
sqldba
It's law in Australia. If you do not serve a notice period you owe the company
wages for that period. 1 month wages minus 1 month notice = 0. Most people
have no notice periods, serve their notice period, or get approval not to
serve it at all.

In this case though (when I followed up with accounting) they confirmed they
wanted to step on my neck.

Even now the entire situation seems utterly surreal. I've been through a few
companies since then and never had any problem, I'm the likeable hard working
quiet person. I guess they just really didn't like me!

Anyway I remember walking out of that office in tears and feeling that no
matter what happened I could cling onto whatever self worth I still had. I
didn't know how bad it was about to become. But I came out okay in the end :-)

~~~
dennisgorelik
Why didn't you give them 1 month notice then?

They would probably fire you immediately anyway and you would get paid.

~~~
jschwartzi
What would you do if they kept you for the month?

~~~
dennisgorelik
Do what they ask me to do, read HN and search for new job.

------
organsnyder
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.

------
jlees
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...

------
mattknox
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.

------
mgkimsal
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?

~~~
yarou
I'm surprised literate programming[0] never really caught on.

Rather than have separate documentation, the paradigm is completely different.
Source code generation is interspersed with the abstract flow of thoughts that
one usually has while developing.

This style of coding seems to be natural to me, as many algorithms are a set
of discrete steps in an abstract sense. Implementing concrete steps and then
describing their abstract counterparts seems sort of backwards to me.

[0]
[https://en.wikipedia.org/wiki/Literate_programming](https://en.wikipedia.org/wiki/Literate_programming)

------
egusa
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."

~~~
debacle
As a corollary, the best person to review your documentation for accuracy is
the new hire.

------
debacle
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."

~~~
bluedino
_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._

So that's why your first project here is going to be writing up some stuff so
that it's easier to bring future people on board!

~~~
afarrell
> So that's why your first project here is going to be writing up some stuff
> so that it's easier to bring future people on board!

Has "get started on a new project by first writing up the documentation"
actually worked for anyone in either a company or an Open Source project? If
so, I would really like to know how because I keep hearing this advice but I
suspect it comes from people who've never done it.

~~~
wpietri
I started a job a few months ago and pretty much the first thing I did was
improve the getting-started documentation, and the next thing was to improve
the build process so there was less documentation needed. Worked for me.

Putting yourself in the mind of a reader is really hard. And documentation,
which is necessarily duplicative, can easily become out of date. So yeah, I
think novices are often the best people to write novice-targeted
documentation, because they understand the reader's needs quite well.

Personally, though, I'd be a little embarrassed to assign a new arrival that
if there were absolutely nothing. I think the process is a lot easier if they
have some starting point for the docs, even if it's just some headings and
bullet points. I'd also sit nearby and give them strict instructions to stop
me at any point they were confused so that I could get them back on track. But
I think it's a pretty good task on arrival.

~~~
peterwwillis
I did this, sort of, but had an interesting problem. Once i'd rewritten the
onboarding documentation (because it was given to me as four or five different
PDFs, which really isn't that useful, and doesn't tell you what you
specifically will need to have set up), there was no place to put it; there
were 3 wikis, none of which anyone really looked at other than for their own
stuff. New hires wouldn't know where to look to find these onboarding docs and
nobody else would know either.

So it just floated around and new hires basically started with the PDF all
over again.

~~~
wpietri
In our case, we just checked in the docs as part of the project. That's not
always the best reader experience, but if they have the code, then they're
sure to have the right version of the docs.

------
luu
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.

~~~
walshemj
So your all individualy developing locally on your machine instead of on a
server that you all use? - I think that's your problem right there

~~~
marssaxman
I'm curious, what subset of the software development world are you working in?
"Developing locally on your machine" is and has always been standard practice
in every part of the industry I have encountered.

~~~
walshemj
Every project I worked on at BT (15 years) and all the webdev work it makes no
sense to have 20 different pcs all developing and trying to merge the code at
the end.

You remove the risk of subtle differences between developers pc's

if your only developing standalone apps I could see it but Microsoft doesn't
develop windows or office that way.

~~~
marssaxman
Perhaps I just don't understand what you're describing, because in my
experience it is completely normal to have developers working on 20 different
PCs and all merging code as they go - that's what version control systems are
for! I can't really imagine how else you would do it. Do all the devs really
mount a shared filesystem with a single copy of the code!?

Or do you mean that the devs all still have individual copies of the source
tree, but they do all their work by remoting in to some big monster server and
building/testing there? That sounds.... um.... ungodly slow. Though I suppose
if you are talking about webdev, perhaps there is no build step, so it might
not suck _quite_ as much...?

It sounds like a very different world, and I'm struggling to understand what
you mean.

I never worked on Windows or Office, but I did work in devdiv for a while, and
at that time Microsoft certainly did develop Visual Studio in the traditional
way. There were build farms, to be sure, but they were used for occasional
checkpoint builds and for testing. For daily work, we ran the ol'
edit/compile/link/run/crash cycle locally, on our own dev machines.

~~~
walshemj
You can have your own source control at the server level and every one logs
into that server just run an X Server on your PC. And yes you should be
developing on exactly the same hardware its going to run on.

All you need to set up a new user is a bog standard pc and a new account set
up on the server.

Its a lot easier to keep dev test and live identical than 20 or so developers
pc's

And even when we did local development (oracle forms) all the code was checked
in to a central server which was used to produce a daily build.

How do you think IBM mainframe development is done?

~~~
marssaxman
Thanks for explaining. That's certainly a very different way of working from
anything I've ever encountered. I don't know enough about mainframes to even
wonder how things are done, it simply isn't part of my world at all.

I come from a personal computing background, where it really doesn't make
sense to talk about "developing on exactly the same hardware it's going to run
on" because you cannot know in advance what that is going to be. The kind of
thing you are talking about makes even less sense in the embedded world, where
cross-compilation is the rule and the target machines are likely not capable
of self-hosting a toolchain at all.

------
breadbox
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.)

------
hosh
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?

------
DasIch
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.

------
cocoflunchy
On this subject, 10% of Airbnb engineers started last week:
[https://twitter.com/mikecurtis/status/633759315480805376](https://twitter.com/mikecurtis/status/633759315480805376)

Kind of crazy...

~~~
scrabble
How many engineers work at Airbnb? If there were 18, that would mean they
hired 2. That's not that crazy.

~~~
patio11
I'd ballpark it as "several hundred." (Edit to add: this was a guesstimate
based on "having a sense for this sort of thing is a key job skill for me." I
then went looking to firm up the guesstimate. Data points in favor: 400 people
match a search for "Airbnb engineer" on LinkedIn. A recent post shows a photo
of their data science team with ~30 people on it; on previous experience with
software companies, I'd have difficulty thinking there aren't at least 5+ much
larger teams.)

More broadly, I think people consistently underestimate how much you can get
done with a very small team at a startup and, simultaneously, underestimate
how many engineers it is possible to throw at a single product.

~~~
tomjen3
What. My ballpark would have been five or less + maybe 200 support people to
handle all the issues with having that many customers.

It is a relatively simple website that allows you to search apartment listings
- essentially a very pretty CRUD app.

What are the rest doing?

~~~
Xyik
Hmm, lets see I would guess they at the very minimum have a: -Web team -Mobile
team -Data team -Infrastructure team -Tools team

So assuming at least 5 people per team thats already 25 people ... why is it
so hard to understand that building anything at scale involves lots of man
power?

~~~
balquhidder
Is AirBnB "at scale"? Why does it need to be?

------
ptx
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! :)

------
dhutchinson
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.

------
snlacks
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."

------
walshemj
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 :-)

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

~~~
dllthomas
"Onboarding" is getting new people up to speed. It's often used in the context
of new employees and sometimes new users.

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

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

