Wednesday, October 15, 2008

The Mystery Sherlock Holmes Never Solved

I'm talking about the mystery of setting up your development environment for the project you are joining. You know, that step-by-step instruction that within 30 minutes leaves you with a complete environment that lets you check-out, check-in, build, debug, deploy, test, run and perform all your daily developer tasks.

Actually, that document is usually nowhere to be found. It could only be recreated by interviewing every developer that ever worked on the project. Sherlock would not have coped.

The plot thickens since this very document is the single most important piece of documentation of any project. And I have proof, Dr. Watson. Let me come back to that in a short while.

Having a good dev-setup instruction is all about respect for the new coder on the team. Do you want him to end his coding days like Sir Charles Baskerville or do you want him to get a good start?

Also, if the setup takes a long time it is a sure sign that the system has grown more complex than it should be. Perhaps it's time for a thorough refactoring.

How would you go about creating this document? I believe it shouldn't even exist. The setup ought to be fully automatized.

If automization isn't an option I would suggest to try something I did on a recent project. Hire an external developer to come in and try out the existing setup instruction. Ask her to follow the instructions while updating them as needed. Time it. If you're not happy with the result, bring in another developer and iterate.

Well Dr. Watson, allow me to present the result of some research I did before writing this post. I asked for the Single most important piece of documentation on At the time of writing the most voted answer by far was "How to set up the development environment".

How is possible that I have never seen a good setup instruction for any project I worked in? Hmm, I believe we got work to do, my fellow coders.

No comments: