project documentation

This post is about documentation, not source code documentation, but project and process level documentatino. I've spent the last 3 days working on a quick side project at work. There were 10 tasks, none of which were very complicated, the time spent tackling these tasks was about 5 or 6 billable hours. The time spent figuring out how to deploy these changes was about 3 days. The problem, project documentation

Scattered Information
Like some sort of 80's Nintendo Game I had to find the various colored keys to win the game. One developer knew the ftp server's ip address, another the username, maybe a third the password. It didn't help matters that this was a fairly complex site made up of multiple components (third-party blog, storefront, cms) each with their own credentials. Collecting this information was the first hurdle to leap in getting the code and getting the job done. It took a solid afternoon of pinging different parties but I finally had a list of keys, the blue door, the red door, even the green glowing door could all be opened!

Out of Date Information
Then came the crushing realization, as I found that the red door was rusted shut, the green glowing door didn't use a key but a magic potion, and no one could remember exactly where the hell the blue door was even located. The information was out of date or just plain wrong, more time wasted pinging people to get updated information and missing chunks. But after another day of haranguing I finally confirmed that the doors could in fact be opened, that night visions of tables and source code danced in my head.

Misplaced Information
This isn't really anyone's fault. I was working on a type of system, let's call it a foo type system, this particular foo system had been customized for client bar. I looked in the foo\bar\ folder for documentation and came up empty-handed. I assumed that there was no documentation and so created some there to collect up the hard earned bits and pieces of information I was able to pull together. Being proud of my new documentation with things logically laid out, I reported to my fellow developers the great leap forward in documentation technology I had developed. I was told there was similar documentation in the foo\ folder, why no one mentioned this to me earlier when I was pulling together this information is beyond me. But it didn't make sense to my brain, if there is a foo\bar\ folder why isn't foo\bar\ information in it, why is it in foo\, ah!

So what is the solution? Knowledge Base, Sharepoint, Wikis, Word Documents, what to do? I don't think that any one of these things by itself is a solution, but I do have some ideas.

Convention over Configuration
If you've ever played around with Ruby on Rails you will know the great joy of feeling at home in a rails project. Where are my models?! app\models\ that's where they always are, that's where they belong. I think adopting a standard documentation layout structure would be useful. Here's an idea (off the top of my head, so its not very polished)

• project-name\documentation - Root of the documentation


• project-name\documentation\bootstrap - How to get started, pulling the project from source control, initial builds, dev box configuration


• project-name\documentation\credentials - IP Addresses, Username, and Passwords go here


• project-name\documentation\database - Everything you'd want to know about the database


• project-name\documentation\deploy - Deployment specifics are here


• project-name\documentation\vendor\* - Third party documentation goes in various folders here

It's not perfect but its a start, really the important thing would be to have some sort of standard and stick to it.

Wikis
I like wikis, I think they are neat. Your documentation is easily editable, so it's easy to keep it up to date, and multiple parties can collaborate to break the task of documenting a system into more manageable chucks. I also think that you should follow some sort of system when writing them. Make this part of the convention and don't stray from it unless absolutely necessary. Maybe the sections above simply become wiki pages, with subpages. Wiki markup is easy to learn for any programmer, and as long as you aren't doing anything fancy, easy to remember.

Document your processes, that's the big thing, it would be great if you have a convention, its awesome if you have some collaboration medium that let's you keep it up to date, but the most important thing is to document the process. It's been eye opening to write out a list of steps for some of the "simple" tasks I do on a project from time to time. Since its become routine in my head the task is one step, do the task, but when I write it out on paper there are 13 steps with small conditional branches. It seems easy to do a task you've done a hundred times before, but it can be maddening to someone new trying to accomplish that task without the help of the well-worn mental path you've painstakingly claimed from the jaws of chaos.

I have been on projects with great documentation, and some with not so stellar documentation, and it is like night and day. So here's a thought experiment, a trite and cliche one, but if your entire development team got hit by a bus tomorrow and some new guys had to come in and deploy, how long would it take them, could they even do it? The answer should be, they would simply bootstrap then look in deploy and follow my step by step guide to deployment success, if your answer was, they would pray and put on their detective hats, ding ding ding, you've got some documentation work to do.