[eire1130]

I agree with both (1) and (2). We require all devs, as a part of the onboarding process to read, improve and correct the docs for onboarding for each new hire. A PR is required. This forces all developers to understand what happens when something actually breaks and also how to locate the information, should the need arise.

This is also why we've never Dockerized. It masks too many issues and no one seems to have a clear understanding of how all the garments are stitched together.

[milesvp]

Very much this. New hires must always be tasked to improve onboarding documentation. At a previous place I worked, I went from expecting it to take a new hire several months to be productive to less than a couple weeks and a big reason was continuing to have newbies tweak docs and fill in details that might be easy to gloss over by soneone who already knows the tech.

As for containers, I’m not sure I follow. We ended up using vagrant and then test kitchen for our VMs, which really helped with on boarding. The team had too many people who couldn’t be expected to troubleshoot much of the backend anyways. We had stayed away from containerization because it added complexity without any clear benefits for our use cases. But test kitchen definitely papered over the need to get a local environment running with all the dependencies, which might change with different services, and that seemed like a good thing.

[trey-jones]

I can maybe give some idea of what he's saying about containers. We do use Docker, and when I mentioned in my original comment that I aimed to lower the skill required to come onto a project, Docker is the primary vehicle for that effort. Here are my reasons:

1. Nobody has to install dependencies. Docker is the only dependency (with compose).

2. Everybody has the same configuration.

3. Software versions are (mostly) tightly controlled. This requires whoever sets up the dev environment to make sure they use specific versions, and not :latest.

4. Devs don't need to spend time worrying about how the dev environment works, just the code.

This means that my README for a project usually has a section describing setup that just says:

1. run `dev/install` (any libraries from eg. NPM, go modules, etc.)

2. run `docker-compose up`

3. Check that the application is running on port XX.

This actually works great, and it does allow new devs to get to work quickly, and it does allow us to use devs that know very little about the underlying software that we're using, unless something doesn't work correctly. And that does happen, much more often than I would like. Then it takes my time and theirs to get up and running, and that was definitely not the goal.

[bluGill]

When I'm asked a question I often respond it is on the wiki. If it isn't on the wiki it is your job to put it there. If it is wrong and you know why fix it. If it is wrong and you fail to figure out why, then talk to me, but I won't respond except to say I fixed the wiki.

That way the wiki stays up to date. Most corporate documents/wikis are worthless after a few years because things change but the wiki didn't. You need to constantly update it.