Resigning as a guru (or how to hand over a project)
No not referring to myself of course ;-). It’s the title of a recent post on Artima . Guru in this context meaning someone who has complete knowledge of a system and knows the system inside out. How do you handle handing over a system or an application to another team or developer when you know the codebase intimately? I've worked on a number of projects where the core key knowledge of large systems is always trapped within a small number of people’s head.
This post was timely for me as I was handing over an old system to another team which I had once been responsible for. So what did I do?
I produced a readme.txt with basic information on getting the app installed, any dependencies and the purpose of all the main folders. This was a ColdFusion app that didn't need building so there wasn't any build instructions or build.xml file.
I bundled the app with cfcdocs so that anyone could checkout the project and go to
http://localhost/appname/docs/ to view the api for all the components involved.
I bundled the application with unit tests. Although this wasn't for documentation purposes, hopefully the tests will go someway to illustrating how various methods in the components should behave.
Finally I produced some written documentation - which included a glossary, high level UML diagrams, sequence diagrams for the main operations and an overview of various parts of the system. I tried not to go into too much detail on things which were likely to change but focus on the high level architecture. Of particular importance I think is documenting the why’s – i.e. what trade offs were made and justifying the design decisions – “why is a .csv file used instead of XML? Why is a factory used? What’s this command pattern all about, why did you choose this framework” etc.
One other solution I hadn’t mentioned was working with someone. Another good way to hand over a system is if the original team and the new team work in tandem for a while, perhaps even pair programming on the system in question. With Webex and GotoMeeting or even Skype this can be done even when the teams are in different locations.
I have more thoughts on documentation in general but I’m interested in how other people approach this.
Kola, I usually just dump and run. cfencrypt all the main functions and
places where people would NEED to change stuff, add a bunch of directories
with random code (make their names very important, like controller, model,
views, configuration, built etc) that dont do anything and after that,
change my phone number and move house. That works fine for me.