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?

5 Answers
5

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.

+1 for the complete toolchain. All the documentation in the world won't help if you can't build and test the software. When possible, I like to include the installation images for all the tools (although nowadays I'd probably opt for a VM image of some sort). Nothing worse than finding out the build process depends on a third-party plug-in from a company that doesn't exist any more!
–
TMNAug 28 '12 at 16:01

@TMN - and that's why I tend to shy away from things like commercial IDE plugins and so forth. I don't trust that I'll be able to reproduce my environment later. And having worked on 20+ year old software, I NEVER assume that anything ever goes away.
–
Michael KohneAug 28 '12 at 16:16

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.