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."
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!
> 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.
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.
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.
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.
> 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.
This is a good insight: the strategy does work if they have something to work through and a fallback if they are confused.
It also depends on the developer. I'd consider it an appropriate task for a mid-level or senior dev who's already familiar with our stack, but not for a junior person or someone transitioning from another stack.
Yes and, since I had a good manager, I was rewarded when "the next person" came along and the amount of time required to onboard dropped from one month to two weeks.
Everything in that situation came down to documentation and I spent my first couple of days just chasing down the "correct" IT person to setup all of my accounts (company network, version control, bug tracking software, customer network, remote access, email - each required a different person and I had to ask around to find out who they all were). I commented that having one IT person who can handle everything would be ideal; but I had to settle for creating a list of "who to contact for what". This still shaved days off the next person's lead time.
Simple stuff like having a development machine ready to go (installing Visual Studio, an Office suite, etc) when the new person arrives really makes a difference. There was a learning curve w/r/t the actual system but the new person didn't have to switch gears between hunting people down, installing a myriad of in-house software with which they have no familiarity, and other general "drinking from the firehose".
I took some stabs at making the firehose drinking not as overwhelming; but I didn't do as well as I wanted.
The organization's attitude mattered, in retrospect. Bringing on new people took a significant amount of time (still does but it's better) and everyone did what they could to help me document the process. I imagine if the organization had not been incentivized to help me, then I would have failed and "first write the documentation" would not have worked at all.
It worked really well for me. I started on a project that had no documentation, no setup scripts, and nobody I spoke to knew how to get it setup. Everyone kind of just got it working somehow.
I setup Vagrant, wrote provisioning scripts, wrote a README, and checked it in after I had figured everything out.
The next employee to join was setup in a day instead of 2 weeks. It worked out great for me.
Anecdotal, but my first job's first project was to take ownership of a codebase my team had just been given from another part of the company which nobody on the team really knew. Ensuring the documentation was up to date (it wasn't) and the other developers on the team were able to get, build, and deploy the codebase to their own VMs was literally the first thing I did--and it gave me a reasonably good basic understanding of the software to allow me to move forward with owning/working on it in the future.
To be honest, it was a kind of frustrating onboarding experience, but it definitely met the team's goals with a minimum of disruption to people who were shipping features.
What I've experienced as someone who has helped onboard new-hires is that we meet with the new-hire daily for a week or two, and throughout that process if we find documentation has gotten stale the mentor usually updates it (e.g., yeah, our baseline OS has changed to xyz, what is here is old, here's where you get the bits for the new stuff), because the new-hire probably has no idea how to fix it yet.
I've used this method before, and so long as you are transparent BEFORE they accept the job, and actually give them the support they need to successfully accomplish this, I've had it work really well.
Also there has to be very clear guidelines - Use the wikki to set up. if you get stuck ask us, but anything you ask needs to make it back in the wikki.
I have never seen a wikki stay 100% in sync with the real world. But make people edit the wikki as part of using it, and things change.
"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."