Catalyst: Recently my team has been tasked with bringing in house a large software project that has been worked on for over 20 years. Some of the old development team is still around, and originally the plan was to have them mentor us and bring us up to speed. After quick investigation, it's been determined that this project suffers from the following:

  1. No testing framework. Everything is manually tested at an integration level and shipped off to the customer to verify the changes.
  2. No up-to-date design documentation.
  3. Limited learning material. The code does a lot of non-standard things(lots of use of configuration files that define business behavior, use of multiple configuration files for GUI [attributes of the GUI can be set in file A.extenion_x or B.extension_y, but not real clear as to why])

What I'm trying to come up with is a list of things our developers can do as they work in order to teach other members of the team, or future members of the team. Basically I just want them to document their learning, and then archive that information.

Luckily the project did take advantage of issue tracking software, so each bugfix or feature change can be tied to a unique identifier. We can then archive the learning material and tie it together with the same id. An example of said learning material, would be a quick write up about the change, a test plan, and other applicable information for the change.

Outside of making use of unit testing (that's the goal, but it's not going to be able to be completed in the short term), what are some other ways we can generate learning documentation as part of our development process.


First of all, you hit the nail on the head: Michael Feathers drives home the point time after time that legacy code is code without unit tests, and this must be priority one when working in legacy projects.

Aside from that, you also bring up issue trackers. I am not sure that they are useful in the context of training and documentation.

I would focus on the architecture. Any project large enough to warrant this amount of effort will have some high-level design consisting of modules (unless it truly is a big ball of spaghetti).

I would have a two-prong approach:

  1. The senior members of the legacy team who know the product need to come up with high-level documentation describing the key points of the software from the perspective of a developer working on the software. This should be very concise, and precisely as long as it needs to be. It should be written such that a developer new to the project has enough context to get started, but is not overwhelmed and drowning in documentation.

  2. Your developers that are taking over the project need to document each non-trivial issue they encounter and how they solved it. They are fresh eyes who are not intimately familiar with the software: odds are if they are tripped up by something, so will someone else. Ideally this would tag on with the previous documentation: a legacy developer documents module XYZ at a high level, and the new developers add in their own lessons learned from dealing with the module, editing it all into one cohesive (and concise!) document.

The end goal should be a concise but useful document that can bring developers up to speed on the software product.

I would probably stuff the documentation into a MediaWiki or something similar to it.

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