Daniel Ford

I was recently reminded of the disconnect between organizational image and organizational reality. In software development organizations one often sees a professed focus on productivity and quality. Sometimes this is bolstered by the sincere adoption of some kind of “development philosophy” that has some spiffy name like “agile,” “srum,” “pair,” or “test driven.” Each approach has some value and the best developers and organizations adopt what works. The problem however, is that many stop there and don’t really think about what would truly make their efforts more effective and productive.

One practice that I’ve encountered, and have tried in practice, is to make it as easy as possible for a new person to join a software development project. This is a simple practice that can payoff big by getting new people to be productive as soon as possible. For open source projects, it’s pretty much a requirement for attracting other developers, because if it is hard to join a project, they’ll simply move on to something else (and you’ll never know). The surest way to do this is to codify the project’s tacit knowledge in an “immigration” document. This is a manual or wiki that you give to a new person that explains EVERYTHING about the project other than its design (and maybe a bit of that too). For instance, simple things like the names of the other developers, their contact information and the parts of the project that are their responsibility should be included. Also, a complete inventory of the tools in use, their versions, where to get them and how to install and configure them is incredibly useful to a newcomer. Administrative trivia is also essential; things like how to obtain an account, where the repositories are, the names of servers and where they’re located, and anything else that “everyone” just knows. A “starting out” check list is also a big help. This is step-by-step list of tasks for a new person to execute, the basic idea is to get them to be instantly productive by setting up their environment without any kind of drag on the rest of the team. The most important component of the immigration document, however, is an accurate, up-to-date explanation of the project’s build process. Why? Well, first, it means that the project actually has a build process! Second, it gives the broadest, least ambiguous, picture of the system being developed. The build process is also a reflection of a capabilities and professionalism of the organization that created it and it sets expectations for the project newcomer, and you want those expectations to be set to the max from day one.

This last point actually cuts both ways, if you’re a developer interviewing with a company and they get to the point where they say “Do you have any questions for us?” You should sit up and start digging for information about their build process. If it involves some guy running between two ancient PC’s with a couple of floppy disks, don’t expect to show up on the first day to a desk, a chair, a computer and the necessary accounts already set up; you shouldn’t expect an immigration document either. However, if the process is completely automatic, look knowingly impressed, throw them a compliment, and then ask to see a copy of their immigration document. If you get one, say “Wow! Where do I sign up?” If you get a blank stare, be nice and explain, interviewers love candidates that that can teach them something.