As consultants, we at Quick Left work on dozens of projects, experiencing all the pains that can make it difficult to become productive as we ramp-up on a new project. These tips apply to anyone who’s developing a project and would at some point bring someone else onto that project. Really, that’s pretty much everyone :). We’ve seen a lot and have a lot of opinions on what it takes to make it easy for a contributor to become productive on a project. Here’s our take on it.
Although the below points may be well communicated in our industry, they’re often overlooked or under appreciated. These basic tools are really the core of making your project easy for new contributors to become productive.
Have a “GOOD” README
It’s very easy to forget to update a README. Nothing’s more frustrating than having a poor README that’s missing imperative steps while you’re trying to setup your environment.
To combat the problem of forgetting to update your README, there’s a few tricks you can use:
- Practice RDD (Readme Driven Development). Updating your README before writing code has a whole host of benefits. The most obvious benefit being that your README is always up-to-date. I’ll be honest, I don’t always edit my README before my code. But, I do try to think about the README for every pull request I submit. Heck, why not add a “Does your README need to be updated?” section in your pull request template?
- Every time a new developer ramps-up on your project, ask them to update the README, fixing any failed instructions or adding any useful information that they discover along the way.
Finally, put some thought into the structure of your README. Some of the common sections are “Frameworks and Libraries”, “Getting Started”, “Testing”, “Staging/Production”. Here’s a more in-depth article on the subject. Keep in mind though, each project is unique and might require other sections.
Write Clean, Well Organized Code
Easier said than done, this is a separate topic in its own right, which is why there are so many books and philosophies on the subject. The goal is to have your code organized in such a way that makes it easy to grok, so that a new contributor can quick understand what’s going on and start making contributions.
I asked around the office about which books on the subject our Quick Lefters like the most. Here are the results in no particular order. Even if you just read only one of these books, you’ll be worlds beyond where you started.
- Refactoring: Improving the Design of Existing Code
- Clean Code: A Handbook of Agile Software Craftsmanship
- The Art of Readable Code
- Domain-Driven Design: Tackling Complexity in the Heart of Software
This piece is arguably the hardest part to learn how to do right, but it’s the most important. When the going gets tough, we may feel like we need to take the shortcut, but the cost is a lot higher than you might think it is. And the cost is often realized when you try to bring new people onto your project.
Have Unit Tests
Every time a new developer joins an existing project that doesn’t have unit tests, a kitten dies.
Seriously, units tests are the only thing that gives a new contributor confidence that they can kill it (not the kitten), build feature after feature, refactor and be productive. You may be able to get by as a solo developer without unit tests, but you’re still just “getting by”. “Getting by” means making changes, breaking things, and then going back and fixing things. This flow requires your whole codebase to be in your head in order to make sure you accounted for everything. If you wrote the whole codebase, then you’re lucky to know how it all works, and you can get by. Now imagine if *you* are just getting by, then how will an outsider feel when trying to make contributions to your project? Having unit tests is an imperative piece of the puzzle!
The Less Obvious Tips
Here are some tips that are less known.
Create a TROUBLESHOOTING Guide
A troubleshooting guide helps cover all of those odd cases that make it difficult to install a new tool, or get your environment setup just right. Basically, anything that might go wrong with setting up your environment, capture the issue and resolution in a TROUBLESHOOTING document. It’s life, sometimes tools that we use don’t work right all of the time. Let’s at least compile a list of those issues, so that new contributors can quick understand and get past them. You’ll be suprised how often you’ll reference the guide even though you may be the person that added that specific issue+resolution.
Create a CONTRIBUTING Guide
Github Pull Requests integrate with a CONTRIBUTING file, calling out your contributing guidelines every time you make a pull request. Traditionally this information would go in the README, but having it separated out into a CONTRIBUTING file helps create focus on what exact requirements are expected of a contribution. Since the guide is flashed to the user at strategic points in the process, it helps increase the chance that your contributing guide is noticed and executed by the contributor.
Some topics that you can add to the CONTRIBUTING guide:
- Style guides.
- Testing requirements (e.g. a minimum thresdhold for test coverage).
- What to try before submitting an issue.
- How to write up an issue (e.g. require reproducible steps to recreate the issue).
Explain your Task Management Tasks
I’m referring to makefiles, rakefiles, gruntfiles, gulpfiles, etc.
Whatever task management tool you use, treat its stucture with the same care you would treat your production code or README. Contributors will need to grok it as easily as they need to grok your code. If you have a lot of tasks and it’s overwhelming how they all related to each other or what purposes they serve, add a section to the README that summarizes the important parts and what scnerios they’re used in. Less documentation is more, so be selective about what really needs to be explained.
There will never be a complete list of tips for every situation. So get creative. The goal is to reduce the amount of time it takes a contributor to setup the project in a local development environment. The measure of success is how quickly they can understand and navigate your codebase, and make their first contribution.