Adam Mackintosh
2 min readOct 21, 2018

--

Documentation will save your new-hire about 8–16 hours of struggling.

In my experience, you should be trying to simulate your production environment, so a Windows development machine would probably work but everyone has to be aware that setting up SSL (for https) is generally pretty annoying on Windows, and it is much harder to compile binaries for PHP extensions, things like that.

I think documentation should state what the viable operating systems are. There are always environment deviations between Windows, Ubuntu, and Mac OS. Your tech stack probably runs on all of them with various pitfalls and gotchas, so good documentation is key.

In my opinion, good documentation for environment setup means the document not only describes how to setup (preferably line by line spoonfeeding) the machine but also describes why tools are used.

You could say something like:
“We use Snappy PHP extension for this project, but we use it for all projects that use images because it is the most performant solution for image compression. Over time, you will become familiar with it, and you should study it so you understand all the features it offers and how it compares to competitors for image compression. Heres how to install it on Mac OS: … Please update these docs if the steps cannot be followed.”

It is always a good time for new hires to contribute documentation. They will feel useful and helpful. So get them to document something that needs to be done, or get them to document processes they are doing or learning so that the next new hire after them doesn’t suffer the same loss of time where they did. It’s like detailing a treasure map for how to find productivity.

--

--

Adam Mackintosh

I prefer to work near ES6+, node.js, microservices, Neo4j, React, React Native; I compose functions and avoid classes unless private state is desired.