MARTYHAUGHT

One thing that you get spoiled with when you work on projects that are well-organized is having good project documentation. I’ve worked on numerous projects all with varying degrees of documentation. I would guess that most projects have poor documentation, if any. How much is this documentation worth? I’m not sure but I can tell you one doc that every project should have that is quite valuable. You could call it Application Dependencies or ‘How to set up your development environment so you can run the application’.

This document is pretty simple in concept and even easier to create. It contains all the steps you need to take to check out the code repository, build the application and run it. Sometimes there may not be much to it but often there are many hidden steps that are not obvious.

What’s the value of this? If you’re solo on a project you might be saying I don’t need it as I know it. I would still do it even if you feel this way. What happens if you get a new machine? Surely you will not work on this app forever and if it’s for a client they will need to be able to reproduce these steps. What about installing the app into a production or staging server? However, the biggest reason is when you need to bring another teammate on the project. I recently went through this on a new project and they had no such doc. I’m embarrassed to say how many hours were wasted blindly stumbling around. The most significant was based on my lack of knowledge that the project had git submodules. You can’t just run a clone command and be off to the races. Think of the money you can save your client, or yourself, if this doc was available. Half a day wasted could be a thirty minute recipe.

So being the good software citizen I wrote this document for them so the next guy doesn’t have to flail about like I did. What’s crazy is this document is a piece of cake to write if you’re starting off on a new project. Before you run a single command create an empty file for these notes. Call it README, INSTALL, development_notes.txt, whatever. Every command you need to run put in there. Document all system libraries and gems you need to get the app to work. The more detailed you are, especially if you can put in copy and paste commands, the easier the recipe will be to follow. It should include assumptions about the base operating system and its libraries, how to check out the code from the SCM, how to run tests, start the app, etc.

The end result of this doc should be a step-by-step recipe that you could hand to a junior programmer and they could go from scratch to a running application without no questions or additional help. Undoubtedly you’ll miss something needed on your first draft. Having another person on a clean system follow your recipe will most likely expose these. Have them update the doc to include anything missing. I prefer these docs to be on a wiki for your team/project but not every team has one so a basic text file is good enough.

blog comments powered by Disqus