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?

  • 2
    consider an easy-to-retrieve list of tickets in issue tracker related to the project
    – gnat
    Commented Aug 28, 2012 at 9:31
  • 1
    As many of the "Why?"'s answered in README.TXT's with the project sources as possible.
    – user1249
    Commented Aug 28, 2012 at 10:32
  • @gnat thanks for the idea. It reminded me that I forgot to mention it. We use issue-tracker with all the tickets. I'll add it to the list.
    – nyxz
    Commented Aug 28, 2012 at 11:33
  • 1
    I'm shedding a single tear of solidarity for your abandoned code base. zdnet.com/blog/projectfailures/…
    – Ben DeMott
    Commented Aug 29, 2012 at 6:45

5 Answers 5


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.

  • +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!
    – TMN
    Commented Aug 28, 2012 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. Commented Aug 28, 2012 at 16:16

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 This is so simple, but makes SO much sense.
    – lwm
    Commented Aug 29, 2012 at 13:38

If you are privy to the information add Business Requirements.

  1. What did the customer want?
  2. How did the changes facilitate that?
  3. What were or are some of the challenges in meeting the customers needs?
  4. 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.

  • Consider opening a new question about upgrading virtual machines.
    – user1249
    Commented Aug 28, 2012 at 10:33
  • @Thorbjørn Ravn Andersen. Your are right. I reformulated the last part of my answer.
    – k3b
    Commented Aug 28, 2012 at 10:43

Not the answer you're looking for? Browse other questions tagged or ask your own question.