Onboarding — Reflect yourself

Orion Delwaterman
Feb 20, 2018 · 6 min read

This is a post I originally wrote in way back in 2015 when I first joined Greenhouse Software. Our blog has since moved to medium and I am reposting it here for all the world to see:

As I write this blogpost, it is day 5 for me at Greenhouse. I really loved the whole interview process with Greenhouse, and I am super excited to get working. But as all new employees know, before you can contribute to your company you have to go through the onboarding process. A large chunk of institutional knowledge has to be transfered from the employer to you. Everything from the individual responsibilities of each job, company culture and guidelines to where the bathrooms are, and where to grab some good food.

For engineers, we have the additional dreaded task of setting up our environment and trying to learn the codebase. Every engineer has to go through the steps of taking that brand new laptop or desktop and configuring it to run the application you are going to work on. I’ve worked for a few different companies in my time and have consequently gone through various different approaches to getting that environment going. Everything from scheduled classes and side by side walk-throughs, to being given a laptop and told to figure it out. Greenhouse gave me a laptop the first day, had a couple of coworkers help me set up some accounts and then gave me a handy wiki page to start building everything out.

As I was building my environment, I was told by many of the engineers to feel free to provide feedback. If I saw anything that was confusing or maybe could be done in a better manner to go ahead and provide feedback. I was super excited to hear this because most companies miss this opportunity. Onboarding should not only be about a new employee learning about their new company, but also their company learning about themselves.

When a new employee struggles to understand something, the company often thinks that something is wrong with the onboarding process. They add new classes or revamp how they are teaching the old ones. But sometimes when a new employee struggles to understand some new process it really means that process is too complex. The onboarding process provides clear feedback on how your company looks to an outsider, and every company should be leveraging the feedback from onboarding to fix the hidden problems within their own organization. This is especially true for the software we write. If a new dev has a really hard time understanding how the code works, or if it takes them forever to set up their environment, you just got a strong signal that something is wrong in your code and you should be investigating it.

So the next time when you onboard a new employee, pay close attention to them during the process. Here are a couple of things to keep in mind:

Your Cognitive Bias — The Curse of Knowledge

Imagine your sweet old grandmother calls you up for help with her email. Something is wrong with her gmail and nothing works. You tell her to push F5 to refresh the browser and she hits the ‘F’ key and then the ‘5’. You get immediately frustrated because how could anyone not know what the ‘F5’ key is. Of course, you are a good grandchild and don’t say anything about it. She’s 90 years old, you remind yourself. She hasn’t used computers for that long and its all new to her.

The initial frustration you are feeling with your poor grandmother (who you never call by the way), comes from a cognitive bias called The Curse of Knowledge. Basically you as a human being tend to assume that other people have the same knowledge that you do and will therefore act as you would. Your brain knows what an ‘F5’ key is so it assumes your grandmother does as well. This is the same thing for new employees. If an onboarding process or code structure seems obvious to you but confounding to a new employee, its not because the new employee is a dud. They simply do not have all the knowledge that you do. More importantly when they get really stuck, whatever knowledge they need to proceed is not easily discoverable. So when you see that smart new dev struggling to set up their environment, this is a signal that something could be wrong.

World standards vs Company Standards

I live in an old apartment in New York City, which means my apartment has some quirks. Specifically, for reasons I don’t understand, the cold and hot water is reversed in all the sinks and the shower in my apartment. Yes, in my apartment cold is on the left and hot is on the right. Now I have lived there for several years so I don’t even think about it anymore. However, whenever someone visits me they are quickly suprised when they turn the wrong knob and suddenly the cold glass of water they were expecting is instead luke-warm. Essentially there is a deviation between the standard US temperature controls and the temperature controls in my apartment.

This happens a lot with software and processes as well. A new employee tries to do something that follows a general standard and is surprised to find out that it doesn’t work. This is your cue as the business that you have deviated from the rest of the world. New employees are the best people to alert you to these differences, because they don’t have the biases that everyone in the company has from working there for years. Just how I no longer think about turning the left handle to get cold water, so too will you easily forget that the patterns you use at your company may not be the same as the rest of the world.

Once that happens now you have to ask yourself: “why?”.

Reasons to Deviate: Historical vs Purposeful

When you are providing an explanation to a new employee about why you would use a bastardized version of XML instead of the accepted world standard, be aware of the type of reasons that you are giving: Historical or Purposeful.

A purposeful reason is a change made to accomplish some goal, whereas a historical reason is a cause and effect history of how something got to the state it is. The difference here can be subtle, but it’s important. Here are two examples:

Elasticsearch is free text search engine that uses a RESTful HTTP JSON API. Basically anytime you want to do anything with Elasticsearch you make a web request with your data as a JSON object in the body. There is one call where this differs: the bulk insert. For this one operation you must supply the data in JSON objects separated by newlines instead of in a proper JSON array. Why not an array you may ask? Because if you had 20,000 objects pased in an array you would have to parse the whole body in one go, whereas objects seperated by newlines can be streamed. Elasticsearch deviates from a standard to make their bulk processing more performant. Elasticsearch deviated from the world standard to achieve a specific goal.

At a company I previously worked at (which shall rename nameless), I had to make a url that would reply with all comments on an article in XML for the company’s search engine. Except that instead of normal XML with the starting XML tag and all the data in a root node, I had to strip it all down to just an a bunch of comment nodes all in sequence. Why was this? Well the guy who original wrote the script to import comments had built it that way and had since left the company. Nobody on his team knew how it worked and so no one ever touched it. This explanation is more about the history of the product, rather than a specific goal trying to be met.

I tend to be very suspicious of historical reasons. Typically these reasons are more about being lazy and/or unwilling to invest in refactoring code, than sound technical decisions. That doesn’t mean that historical reasons can’t be good decisions, say for instance you are Facebook and you have too much data to run migrations. But chances are more likely that your historical reasons are pretty poor. So if you hear yourself explaining something to the new dev by recalling the history of something, you should be immediately suspicious of this decision.


As you go through this process with new hires, remember that none of these signals will tell you whether something is bad or good. It’s just a good place to take some honest reflection. Maybe your company has a very good reason for WSDL files, or using non-standard XML. But the important thing with these roadbumps is to have conscious reasons for the hard parts of your apps. This honest reflection will help point to great refactoring points and should improve the quality of your code overall.

Greenhouse is smart enough to ask for this type of feedback, and I am excited to get working here. Want to join? Apply here.

In the Weeds

A blog by the Greenhouse Engineering team

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store