Re:How to Onboard Software Engineers
by peterwwillis on Wednesday August 26, 2015 @11:56AM
(#10123779)
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.
Re:How to Onboard Software Engineers
by cauterized on Wednesday August 26, 2015 @10:28AM
(#10123083)
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.
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.