5 ms·

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 li

by patio11 11y ago

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 11y ago
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/
- patio11 11y ago
  I like this idea a lot. We're going to steal it.
- mseebach 11y ago
  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.
- leftnode 11y ago
  Yup, it's a great idea! In all of our applications we have a build-dev shell script that builds the application for development purposes. New developers day 1: vagrant up; vagrant ssh; cd /path/to/app/on/vm; ./build-dev And they're ready to go.
- peterwwillis 11y ago
  Very similar to this, I like to say that automation is documentation. Of course, actual documentation is better, but compared to no documentation, a script or automation or test is better than nothing. I used to do this just because i'd forget how to do something so I wanted a written down example of it, and then I make it into an actual program, and then I automatize it. You wouldn't believe how many people end up depending on these crap little examples. And of course READMEs in every directory in a tree that explains what everything in that directory is and what it does.
- abulman 11y ago
  That's the background on a couple of tweets I've already sent today - part of a 56! post sequence (3/4 done, I'm splitting it up a bit). https://twitter.com/alister_b/status/636563590288437248 https://twitter.com/alister_b/status/636563590288437248 - 29/ If I start work and have to spend 3 days just getting the dev site running locally - we know the live site is also a pile of crap There's a plenty more of along similar lines about recruiting, interviewing, and the working environment - both for people, and the code. When I'm done, I'm putting them all together in a blog post with some extra thoughts as well.
hiou 11y ago
That's a great example of practical documentation. I just want to add that for a fair amount of developers they are not going to be successful unless they get an hour+ meeting a couple times a week for the first month for questions and a general birdseye tour of the architecture. Things like "I know most people do this, but we are expecting to swap this feature out in two months so that's why it's put together like that so just roll with it and spend a few extra minutes manually testing before you ship it." or "Employee X is in the middle of refactoring all of this but is putting out a fire for the next couple weeks. If you need to do something here get in touch with him and what you want to do and he'll either walk you through it or apply the fix himself". Unfortunately the personality type of a 10x developer is often not going to be like your 1-2x developer. Pointing them to some documentation and walking away often will lead to an unsuccessful onboarding. This may be preferable if you are actively testing out the new hire and really want fully independent developers, but if you are not knee deep in talent some verbal onboarding can work wonders.
stephendicato 11y ago
That quick hack is exactly the approach we've taken with new technical hires this summer. We are a "vagrant up and go" shop, but there are a bunch of steps between handing someone a laptop and running your app in vagrant. We took the time to document the process and used it in onboarding. We made it explicitly clear that if you notice issues, please fix them, which has the intended side effect of familiarizing the new hire with our development practices (pull requests, reviews, etc). It worked extremely well!
w0rd-driven 11y ago
Thanks a ton for this. I've been recently looking for examples to follow as no readme or style is perfect but this is a worthy goal for any software project to me, be it internal or external, closed or open source. I think the key to make it successful is to have the feedback of someone actually working through it, finding the pitfalls or shortcomings, and correcting as they go. I know I tend to "just figure it" out but I've been in plenty of places with little to absolutely no documentation. It behooves me that if someone did take the time to document something, I should honestly take the time to "pay it forward" by keeping it current as I work through it. It's also far too easy to let this learned skill stagnate when you aren't required to document anything so absolutely no one does it.
okaram 11y ago
This sounds like a great approach; however, what is precluding you from making this into a script ? Maybe with a first step of "fill values in this properties file" for passwords etc ?

by patio11 11y ago

nemild 11y ago

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/

patio11 11y ago
I like this idea a lot. We're going to steal it.
mseebach 11y ago
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.
leftnode 11y ago
Yup, it's a great idea! In all of our applications we have a build-dev shell script that builds the application for development purposes. New developers day 1: vagrant up; vagrant ssh; cd /path/to/app/on/vm; ./build-dev And they're ready to go.
peterwwillis 11y ago
Very similar to this, I like to say that automation is documentation. Of course, actual documentation is better, but compared to no documentation, a script or automation or test is better than nothing. I used to do this just because i'd forget how to do something so I wanted a written down example of it, and then I make it into an actual program, and then I automatize it. You wouldn't believe how many people end up depending on these crap little examples. And of course READMEs in every directory in a tree that explains what everything in that directory is and what it does.
abulman 11y ago
That's the background on a couple of tweets I've already sent today - part of a 56! post sequence (3/4 done, I'm splitting it up a bit). https://twitter.com/alister_b/status/636563590288437248 https://twitter.com/alister_b/status/636563590288437248 - 29/ If I start work and have to spend 3 days just getting the dev site running locally - we know the live site is also a pile of crap There's a plenty more of along similar lines about recruiting, interviewing, and the working environment - both for people, and the code. When I'm done, I'm putting them all together in a blog post with some extra thoughts as well.

hiou 11y ago

That's a great example of practical documentation. I just want to add that for a fair amount of developers they are not going to be successful unless they get an hour+ meeting a couple times a week for the first month for questions and a general birdseye tour of the architecture. Things like "I know most people do this, but we are expecting to swap this feature out in two months so that's why it's put together like that so just roll with it and spend a few extra minutes manually testing before you ship it." or "Employee X is in the middle of refactoring all of this but is putting out a fire for the next couple weeks. If you need to do something here get in touch with him and what you want to do and he'll either walk you through it or apply the fix himself". Unfortunately the personality type of a 10x developer is often not going to be like your 1-2x developer. Pointing them to some documentation and walking away often will lead to an unsuccessful onboarding. This may be preferable if you are actively testing out the new hire and really want fully independent developers, but if you are not knee deep in talent some verbal onboarding can work wonders.

stephendicato 11y ago

That quick hack is exactly the approach we've taken with new technical hires this summer. We are a "vagrant up and go" shop, but there are a bunch of steps between handing someone a laptop and running your app in vagrant. We took the time to document the process and used it in onboarding. We made it explicitly clear that if you notice issues, please fix them, which has the intended side effect of familiarizing the new hire with our development practices (pull requests, reviews, etc). It worked extremely well!

w0rd-driven 11y ago

Thanks a ton for this. I've been recently looking for examples to follow as no readme or style is perfect but this is a worthy goal for any software project to me, be it internal or external, closed or open source. I think the key to make it successful is to have the feedback of someone actually working through it, finding the pitfalls or shortcomings, and correcting as they go. I know I tend to "just figure it" out but I've been in plenty of places with little to absolutely no documentation. It behooves me that if someone did take the time to document something, I should honestly take the time to "pay it forward" by keeping it current as I work through it. It's also far too easy to let this learned skill stagnate when you aren't required to document anything so absolutely no one does it.

okaram 11y ago

This sounds like a great approach; however, what is precluding you from making this into a script ? Maybe with a first step of "fill values in this properties file" for passwords etc ?