Summary
How do you transfer knowledge about a system in an optimal way, without forever being the 'guy who knows'? What practices will help you exit gracefully? Or, even if you aren't leaving this area of the project, how do you lessen the documentation burden?

On the What questions would you ask? thread, Marc Loxton says: I want to do this in an agile way though not by writing a truckload of documentation describing the tech aspects of the system, the direction i want to go with it, which parts I want to phase out and what they should be replaced with etc. I've been having some success with pair programming for some tasks but I'm wondering what do others do to share the knowledge without becoming a novelist? A Wiki with a list of key points? A Brief README file and verbose comments in key areas of the code/tests?

I think the answer is all of the above

You also want to leave a legacy which can be maintained

• README documents (I start with AAREADME so it stands out) are essential when looking at a directory and trying to figure out things like:
  • What tools do I need to be able to use this code?
  • Where are the tests?
  • What is this stuff for, what projects does it relate to? (great spot for Wiki links).
  • What build settings where changed for this Visual Studio project other than just running the AppWizard?
  • What environment variables need setting to be able to build, run, debug?
• Wikis are good, I'm a big believer. They work well with other link-friendly systems. Your issue-tracking system and repository should make it easy to copy stable links to embed in wiki pages.
• Verbose comments in key areas are really good if they will be maintained. I am a huge fan of Doxygen because it makes it very easy to embed comments right next to code as well as writing independent pages describing the software. Unlike many other code documentation systems, Doxygen can parse your C++, Java, Python or other code and immediately generate class diagrams, lists of classes and members, call graphs etc. You can choose to generate fully annotated, hyperlinked documentation so it is easy to go from explanation to code and back.

Talk Back!

Have an opinion? Readers have already posted 14 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Andy Dent adds a new entry to his weblog, subscribe to his RSS feed.

Digg | del.icio.us | Reddit

About the Blogger

Andy is a free-lance developer in C++, REALbasic, Python, AJAX and other XML technologies. He works out of Perth, Western Australia for a local and international clients on cross-platform projects with a focus on usability for naive and infrequent users. Included in his range of interests are generative solutions, software usability and small-team software processes. He still bleeds six colors, even though Apple stopped, and uses migration projects from legacy Mac OS to justify the hardware collection.