Last night I had the following exchange on Twitter:

Having just jumped on board to a newish Django project here at work, I feel their pain. Although I don’t know the Django ecosystem as well as Rails, I do know that projects should contain a readme, and I shouldn’t have to:

1. execute server runner
2. install missing lib or package that it complained about
3. goto: 1 until working

Every development project, no matter how complex, should have a repeatable, predictable (preferably scripted) new developer project bootstrap.

Why?

• New developers can get their machine(s) setup and commit/deploy on the first day
• Existing developers can easily upgrade to new machines without spending days getting it all setup again
• Light-duty hackers (support folks) can have a copy of the site running locally (super awesome for debugging and general playing around)
• Designers can tweak styling, implement new designs, etc. without needing to involve a developer
• Spinning up throwaway testing/dev servers becomes very easy (you can treat them like a dev box)

A repeatable, predictable project bootstrap should, minimally, consist of the following:

• A root-level README that explains exactly how to setup the project. This should contain step-by-step tasks (start with git clone ...)
• A script to install pre-requisites (likely one for OSX, Linux)
• A script to bootstrap their data storage (build the structure, load default users, etc.)
• A script to deploy to staging/production

Root level README

This is your project’s bible. It’s in the project because web pages, wikis, and spec docs all have a way of disappearing.

The README shouldn’t contain any marketing speak about the project. It also shouldn’t contain any architectural documents, the history of the company, or anything like that. It’s simply a list of steps that you need to perform to get the app up and running on your machine, depending on your operating system.

This is the first thing a new person on the project will read. As part of a new hire’s “orientation” you should create a task in your tracker to “Follow the README”. Sometimes, but not often, some change may have invalidated the README. Part of the new hire’s job will be to fix the process to reflect the new project state.

It should also be part of standard operating procedure to follow the README when setting up a new developer machine (as old ones are swapped out) and any bugs immediately addressed.

Like code comments, broken or out-of-date project bootstraps are worse than none at all.

The README should also include any relevant links to the project wiki, bug tracker, project management, chat rooms, etc.

It should be opinionated – if you’re on ruby pick rvm or rbenv. If you’re on Python/Django, have a virtual environment. OSX? Homebrew.

This is not a negotiation – some level of consistency and standardization is a good thing. Don’t get carried away: let developers choose their own text editor, browser, etc. but project-level standards are expected to be enforced.

My README template is (loosely):

• External Links (wiki, bug tracker, chat)
• Dev setup (assuming a fresh machine – so this may include installing git, homebrew)
• External dependencies and versioning (if applicable)
• Project conventions that deviate from the norm (if you use some weird test runner…)

Scripts

Where at all possible – script script script! Yes, you could tell the developer the series of commands to create a new user in the database (I’ve seen raw SQL insert statements in a README before! Eeek!) but it’s far better to run ./setup_db.

Obviously a script introduces overhead but a good team, over time, instinctively seems to find a good balance of scriptability vs. maintenance.

Deployability

A hallmark of a great engineering process/culture has new hires deploying on their first day. This is only possible if the deploy process is scripted. The README should say how to deploy to the various environment(s) and if there are any externalities to resolve (ssh keys).

Edit – May 4, 2012

Some folks have suggested Vagrant + Chef or Puppet as a solution to the problem. I haven’t used it at all, but it certainly looks promising. I’d love to build a Puppet-based config for my local machine (we use Puppet-based Moonshine on our servers, so I’m not entirely sure why I didn’t think of it) and I suspect that’s what I’ll try first.

My only hesitation is that I primarily use a MacBook Air and, although a perfectly capable development machine, running Ubuntu on VMWare is intolerably slow. Benchmarking is probably a task for another day.

There is a big brouhaha because Facebook COO Sheryl Sandberg “admits … walk[ing] out of this office every day at 5:30”.

Oh, the shock and horror. The wailing and gnashing of teeth.

Why is this news? Why do folks think that working gobs and gobs of hours, as software developers, leads to better software, faster?

Sure, for something repetitive and methodological like bricklaying, you can crank up the hours worked dial and see the wall getting built faster. And, sure, there’ll be small bugs here and there (sloppiness as the worker gets tired, etc.) but generally nothing that will materially affect the structural integrity of the wall.

Not so in software development, however. It’s been my experience that productivity falls off a cliff not far after 40 hours a week, and quickly goes negative as developers start adding more bugs than features.

Pretty soon, however, the bugs are not small, easily cleaned up after ones, but those that will cause you to go massively in debt. These kinds of wrong architectural decisions when uncovered days/weeks/months later will bring the whole project to a halt while the extent of the damage is estimated and then repaired.

It kinda looks something like this (completely made up but feels approximately correct):

That’s why one metric I have software developers track per week is whether or not they feel they are on a sustainable pace. Hours are a reasonable approximation of sustainable pace (e.g. on average, don’t work much more than 40 hrs/week) but not sufficient. Frequent check-ins are crucial to establish what “sustainable pace” means for each individual software developer.

Given that we also follow the “Results Only Work Environment” total number of hours worked doesn’t really mean anything anyway. With ROWE, you work wherever you want, whenever you want. Every meeting is optional.

All that matters is:

1. Are you getting your job done, awesomely?
2. Are you, individually, working at a sustainable pace?

Or: Every Developer gets an Amex

How often does this happen where you work:

1. Developer begs, pleads with boss to go to technical conference
2. Boss negotiates with developer on getting a cheaper hotel. (It’s only $69 a night! Clean sheets optional. 30 minute bus ride from conference. What a steal!)
3. Boss orders developer to get cheaper, three stop flight instead of more expensive non-stop
4. Developer attends conference
5. Developer returns from conference with a pile of low value receipts ($20 for lunch, $40 for cab to airport)
6. Developer spends two hours painstakingly scanning each receipt and constructs a spreadsheet with itemized list of charges
7. Boss approves charges without even looking at them
8. goto 1

How brain-dead is this? Here you have a highly-paid software developer doing super-low value data entry. It probably cost you $200 to have them enter all this junk.

What does this tell the developer?

• I don’t trust you
• Scanning receipts is more valuable than writing awesome code
• Your time is not particularly valuable
• I don’t trust you

Give the developer a corp Amex, ask them to be a responsible adult, and be done with it. Have them forward receipts (where applicable) to a specific email address to satisfy potential IRS complications. The end.

Anything else is over-optimization of a low-probability event (being audited and needing to justify a latte at the airport).