So the project I’ve been working on is now going to be frozen indefinitely. It is possible that if and when the project unfreezes again, it won’t be assigned to me or anybody from the current team. Actually, we inherited the project after it had been frozen before, but there was nothing left by the prior team to help us understand even the basic needs of the project, so we wasted a lot of time getting to know the project well. My question is what do you think we should do to help the people after us to best understand the needs of the project, what we have done, why we’ve done it, etc. I am open to other ideas of why should we leave some tracks to the others that will work on this project also.
Some steps we already have taken:
- technical documentation (not full but at least there is some);
- source-control system history;
- estimations on which parts of the project need improvement and why we think so;
- bunch of unit tests.
- issue tracker with all the tickets we’ve done (EDIT)
What do you think of what we’ve already prepared and what else can we do?
4
Some more things to consider
- Is the project directory structure sane? Have you revised the code comments? Is the commit log someway presentable?
- Gerneral purpose overview (as opposed to technical, which you have
started), Advised reading on the project, project history ( its
development cycle, previous project managers, list of staff,
requirements/feature specification) - UML diagrams, class diagrams, work flow diagrams!
- Reasons the project has been frozen is always nice.
- Development environment, IDEs that have been used, build tools, these are covered in the technical docs right?
I just thought of some of the things I would have liked to see on a project I recently inherited. What you have already provided is a hell of a lot more than what I got. You will receive major karma points for helping the next team out 🙂
The things I would like to have when picking up a project someone else has put down are:
Build instructions, including the last known working versions of all the tools in the toolchain. Compilers, IDEs, etc change over time, and it’s a lot easier to work with if the previous devs leave me instructions on how to get up and running.
Run environment instructions – what needs to be in place to run this thing? A mention of what versions is again helpful. I recently picked up something that required a certain set of files to be in a certain place, and I had to go quizzing the other devs to figure it out. Not a big deal since the other dev was available, but if he hadn’t been, then it would have been problematic.
Some assurance that the code committed to the repository actually does checkout and build. I once picked up a project where the previous devs (fortunately still around) had done some truly odd things with the Makefiles such that you could not build the project from a clean checkout. Needless to say, I first had to rectify THAT before I could actually do any work. Had the previous devs not been available, it might have taken a lot longer to get past that hurdle.
A general statement of the intent of the project. What’s this piece of software for? As short as reasonable, but some kind of overview can be really helpful.
2
A ScreenCast
When I left my last job I actually did unedited screencasts which, from what I’ve heard, were very helpful in onboarding new people. I took my team in a room, set up a condenser mic and explained to them everything I knew about the project while recording the audio and screen. Then, I let them ask me questions about it. We were able to get much more information recorded than we could if I sat down and tried to type as fast as I could all day.
1
If you are privy to the information add Business Requirements.
- What did the customer want?
- How did the changes facilitate that?
- What were or are some of the challenges in meeting the customers
needs? - What needs were not met and why?
A virtualmachine image (i.e. vm-ware) of a running-stand-alone developping system might be quite valuable.
Last year i was asked to fix some vb3 code. It was quite difficuilt to re create a running system with vb3, windows95 and a lot of installed ole-controlls. After a week I gave up 🙁
[Update]
Has anybody experince with converting old virtual-machine images so that it can be played in a newer virtual-machine-player?
You also have to consider that it might not be possible any more to run a very old image on a modern hardware/guest os.
2