5 ms·

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 y

by debacle 11y ago

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

brianwawok 11y ago
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.
bluedino 11y ago
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!
- Timmons 11y ago
  This comment has caused me flashbacks to a terrible place I worked at that did exactly this.
- __abc 11y ago
  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.
- afarrell 11y ago
  > 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.
  - bluedino 11y ago
    It worked really well. The only problem is people saying, "Hey, employee #13 caught on so much faster than employee #12, what's up with that?"
  - wpietri 11y ago
    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.
    - afarrell 11y ago
      > 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.
    - 11y ago

by debacle 11y ago

brianwawok 11y ago

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.

bluedino 11y ago

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!

Timmons 11y ago
This comment has caused me flashbacks to a terrible place I worked at that did exactly this.
__abc 11y ago
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.
afarrell 11y ago
> 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.
- bluedino 11y ago
  It worked really well. The only problem is people saying, "Hey, employee #13 caught on so much faster than employee #12, what's up with that?"
- wpietri 11y ago
  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.
  - afarrell 11y ago
    > 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.
  - 11y ago