I'm always happy to see an organization I'm working with recording "lessons learned" documentation from multiple iterations of the same product, or successive project engagement.  The real key however is taking this information and turning into action items that help you get further along.  Too often I see teams committing items to Lessons Learned documents more like a confessional than a plan to not make the same mistake, or repeat a successful technique.

There are some simple steps we can use to help ensure a learning experience:

1. Document collaboratively.  This will avoid personal attacks and maximize the effort. I find it best to conduct several short meetings to get this done than one long one (again no confessionals here).
2. Successes and Failures.  Too often people are quick to point out failures but its just important to make sure we don't miss the things that worked well the next time.
3. Everyone Participates.  These sessions aren't just for the PM's, get everyone involved in the project involved.  This would also include your outside vendors if the relationship allows.
4. Rinse and Repeat.  Take your list of Lessons Learned and put them into documents used in every project Initialization phase.

Thats about it.  Hopefully we are all a few short steps away from the next level of productivity.

CRHC9HJBHU87

I'm writing this as I'm assisting an organization I've worked with frequently conduct a code review on a project they had purchased (from a CMMI Level 5 certified off-shore firm).  I had no role in the original application or any of the functional requirements so mostly I'm just a second set of eyes here. One thing (or rather the lack thereof) is jumping out at me as I'm listening to the narration.  Although the code is definitely well formated C# source, my eyes usually head right to the coders comments first, look at what they are saying they are doing, and following along with a copy of the design documents close at hand to make sure we are on track. 

In this case there was little to focus on for code comments, there weren't any.  A decent design document with UML models, good Use Cases and User Stories, just nothing to get from the class library name to what they were trying to do in terms of walking the reader through the logic or explaining the flow once you hit the source.  Now some of you may say (as they did) that good code is "self documenting".  Well to some extent that may be true, be it fails to answer a basic question I always try and answer when conducting or participating in a code review: what was the developer thinking when they wrote this?

Aside from the obvious issues of navigating fairly complex code, there is also the larger issue of maintaining a code base for code re-use.  Additionally if you are using a project as a template for more junior developers to build from (as this organization was) well commented code is usually more value than any other form of documentation.  If you are a lead developer on a project like this, staying with easy to follow design patterns should take precedence over gaining a little bit of performance (or showing off your coding skills).  So how much is too much ?  Personally, I'd rather error on the side of stating the obvious rather than taking a chance on loosing the audience.  When in doubt, explain it, especially if you are introducing a new technique to the team.