Comment by trey-jones | Hacker News Reader

Comment by trey-jones | Hacker News Reader

Parent Full thread

A good story, and I find myself in a similar position (the one who writes the docs). I think a lot about this topic, because as our company grows it becomes more and more important, and more and more difficult to impart all of the scattered knowledge on new hires.

I really enjoyed this read. I think it contains actionable suggestions that I will incorporate into my job. Consultable documentation, all in a single location sounds like an improvement over what I have now.

The focus of my approach has been a bit different so far: since I know that nobody reads the manual, I strive to make the manual short: "Run this one command and it will do everything for you." My thinking is also that it lowers the bar of skill for new hires. There are some unfortunate consequences of this:

1. Maybe we don't want to lower the bar of skill after all (maybe we do - good workers are hard to come by where we are).

2. I am something of a single point of failure. If I go, I'm sure things will still get done, but it won't be done well (very subjective of course).

Anyway, I'm excited to try and improve my processes to make it easier to grow.

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.

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.

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.

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.

I am a proponent of the lowest common denominator model of development. Basically this means that whatever you develop should be understandable by a relatively new or junior developer. You should develop in such away that a someone coming in off the street should be able to pick up where you left off with minimal effort. This is partly about code, but also docs. Think about the next guy/gal. Is your code clean and well commented? But do you also have docs explaining the bigger picture? Think about what sort of documentation would have helped you get up to speed with the project. If people have to use compile errors to figure out what needs to be done to get up and running then you could have done better.

Reply on news.ycombinator.com