Your project is not ready for contributors, part II

Two weeks ago, I introduced my manifesto for contributor readiness in this article. To American readers a manifesto sounds somewhat sinister. Let’s just say I am taking back the term and using it the way British politicians do.

As I mentioned at the time. A project cannot be considered contributor ready until the project lead has addressed the following five concerns:

1. Access
2. Environment
3. Data
4. Tools
5. Testing

Today’s topic is environment*. Environment is the part of the setup where your developers usually spend their first day of work. They install the myriad of packages and dependencies that come standard with a modern dev workflow. The usual suspects: ImageMagick, SASS, RVM, NVM, JVM, JDK, HomeBrew, Cygwin, WinGit, Postgres, MySQL, MongoDB, Docker, Selenium, PDFtk, PATH variables, and the whole nine yards.

Much of the environment discussion falls in line with talks about access. It’s about providing the right information in the right places.

Where access has security concerns, environment does not. Environmental issues come from areas lacking clarity. Dependencies, modules, and tools get added. Documentation is not updated.

If you’re the team lead and you’ve been on the project for awhile, I recommend getting a new computer and trying to set it up. If you can do everything from the documentation, well done! If you have to look at your existing machine’s setup, you’ve got work to do.

*This installment does not take into account the concerns that your teammate will bring with their own tooling: IDEs, VIM, key mappings, debuggers, proxy analyzers, graphics tools are for part IV. Do know that these tools will bring their own concerns in how they interact with your environment. You are responsible for providing good answers, but only to a point.

Documentation

Most team leads feel more than enough guilt about the lack of decent documentation on their project(s). To add to your guilt, I am equally critical of ignoring documentation. Despite that, it’s not worth writing a rant on bad documentation. Instead, I recommend considering this from an investment standpoint. I offer an experiment, here are the parameters:

Poor Documentation

• 6 hours of new hire time used for environment setup
• 2 hour of senior developer time (you!) used for questions
• 2 hour / month developer time (on average) for environmental issues that crop up

Let’s assume your developers are working 1,800 hours a year. For your reference, that’s 40 hour weeks, ten national holidays, four weeks of vacation, and one week sick. I know very few product teams that are that generous with vacation time, but let’s go with a conservative estimate here.

You have two teams of five developers. You’ve also had three people turn over this year.

• Yearly total: 18,000 hours
• Yearly lost to employee environment setup: 13 x 6 = 78
• Yearly lost to senior developer questions: 13 x 2= 26
• Yearly lost to ongoing environmental issues: 10 x 2 x 12 = 240

(78 + 26+ 240) / 18,000 = .0191 (2%, roughly)

I’m being quite conservative here with the estimates. But 2% is an interest rate some smart savers would kill for at their local branch. What’s worse? You as the senior developer will end up losing out on (6 + 26 + 24) / 1,800 = .031 of your hours this year. That’s roughly 3%, and your time is on the more valuable end of the spectrum. Because junior developers are coming to you for questions, you’ve not only wasted their time, you’ve done even worse to your own time. If nothing else, this should be in the reverse.

Of course, interest compounds throughout the years. Your low productivity will get worse as you move to year five. Let’s take a look at that:

Team: 98%⁵ = .903 or 90%

You: 97%⁵ = .859 or 86%

As your team grows you will thoroughly pay the cost of malinvestment in documentation. 10% cost is the cost of one teammate. So you can rest-assured that one person you hired will exist solely for the various needs that arise from poor documentation in a five year period.

We have not even talked about developer burnout, or that junior developers will be less likely to report their failings and possibly leave, feeling insufficient. This is all conjecture, but I would not leave it to chance.

Create simple, thorough documentation. Make it easy to find. It should be in the README.md unless you have a supremely compelling reason. Everyone knows that standard. Don’t fight the bad fight to make documentation complex. Keep it simple, keep it in a standard place.

For some good thoughts on documentation and its pure value check out A documentation crash course for developers for Chris Chinchilla.

Versions

I can’t tell you how many projects I have opened where the desired version of the runtime or modules is not entirely clear. Gemfiles, packages, etc. do a lot of the heavy lifting. It’s still murky when you have ‘^cool.version.number’ and ‘~magic.version.number’ in the mix.

Beyond packages, make sure your team knows the runtime versions. This is the kind of problem that is rarely an issue on day one. “All the modules and the runtime version are the latest” “Let’s take the afternoon off!” “NPM is awesome!”

Two years later: “What node version was this?” “What version of ImageMagick?” “What kind of project is this anyway?” Things get real hairy real fast.

Good documentation is likely to help this problem. There are other things you can do with versioning. For instance, make sure versions are listed in the package from the moment you start the project (insert your respective package manager here as well). From there, make it easy for your developers to run in the environment with automatic configs like .*rc files or environment setup scripts.

Every time a junior developer comes to you with a problem that is born out of the wrong version of runtime / framework / etc. you need to slap yourself in the face because you’re racking up the cost of malinvestment.

Dependencies

One of my favorite quick reads is How it feels to learn JavaScript in 2016 from Jose Aguinaga. In short: dependencies are here to stay.

Project dependencies are typically managed by the framework or build manager. Beyond that, there are numerous dependencies of a more dubious relationship. Application dependencies like ImageMagick or PDFtk; global module dependencies like Grunt, Gulp, or Yeoman; or testing dependencies like Selenium and its various drivers.

I am not a proponent of rewriting these installation instructions altogether, Sometimes they are very complex. Instead, provide the blog posts, corporate docs, Stack Overflow posts that helped with your setup. If it’s very jumbled (three or more posts), consider giving back and putting all the material together in a public forum.

What you want to do is 1) Keep down the wasted time from environmental questions. 2) Keep down the much more egregious problem of development work happening in an incompatible environment. In the second case, you could have junior developers write large and brilliant features dependent on async await. That’s all fine and good if it’s supported. If it’s not, slap yourself in the face again.

Containers

I did a small, server-rendered, rails project for my church, recently. They needed some help with the web development and enlisted the X most knowledgable people in the congregation to make it happen.

When given a random team from multiple backgrounds. It is certain that you cannot rely on a standard level of familiarity with tools. I bring this up, because I decided to use a docker-compose development container to create our development environment for everyone’s use.

The composed containers ran the Rails environment and the Postgres database. I created test data scripts to seed the database (more on that in part III). The results were better than expected. I had designers and developers new to Rails up and running their environments in minutes. I could even share the database.yml file for credentials, because I knew all the environments were going to be the same.

I think Docker is not the first, but certainly one of the most accessible ways to make containerized development (and deployment) much easier. If you’re looking for a good introduction regarding the ‘what’ of Docker, I would check out A Beginner-Friendly Introduction to Containers, VMs and Docker from Preethi Kasireddy.

The container approach is environment readiness +1. It encases the project environment in carbonite. It acts as live running documentation. Because everyone is developing in the same container, it forces accountability. New changes are automatically added to the Dockerfile(s). It’s a great foot to start on, and I am working to make it standard in my workflow.

That does it for my take on managing environments for your developers. The bulk of the work is the regular, boring stuff of providing documentation and clarity. Remember, your job as a senior developer is to empower others. When you frame this topic in that lens, it’s much easier to spend your day perfecting the documentation. This is despite the fact that it always seems thankless. I appreciate your comments and feedback.