Thursday, April 28, 2011

After pair programming comes – team documenting

A friend of mine, Jan, who is consulting at a major telecom company came up with a real nifty idea for how to make documenting smooth and well, almost - fun…

You recall how it’s normally done, right? One poor team member has to “volunteer” to the far from glorious mission of updating the system documentation to reflect the system updates that the team made in the sprint. So the poor guy has to write down everything he knows and then walk around and interview the rest of the team to get everything right. This task normally takes longer than expected because:

a) It’s so boring so you take every opportunity to get distracted.

  • You go get yet another cup of coffee.
  • You join a discussion between fellow developers.
  • You check that interesting website about nhibernate.
  • And so on

b) The person you need to interview is busy.

Once the document is updated, you normally have to have at least one boring review meeting to get everything right.

So in order to get around these problems my friend decided to try “team documenting”.

He gathered the whole team in the team’s war room, then he connected his PC to the projector and started updating the table of contents, when he ran out of new headings for the TOC, one of the other guys chipped in until the team was happy with it.

So they started on the first chapter, the guy who had written the code started formulating the text while my friend was typing. The other guys commented if they didn’t agree with the content or the wording. A few extra PCs where brought in so that the guys who weren’t typing could look up facts, run simple tests or chat with other people that had input. If there were the slightest hesitation, one or two runners were sent out to question the person who had the information.

There were always at least three people actively involved at any given time, usually more. People who were new to the team and didn’t have much to contribute also benefited from the session since they became educated on the design and also got the history and the reasons why the code was written the way it was.

The person behind the keyboard also became the moderator/enforcer so after a while, he got tired and gave the keyboard to the next in line. This procedure was repeated until all chapters were updated/written. The document was DONE, no need to review because that was DONE too!

The advantages with this approach are:

  • It’s fast (even counting man-hours)
  • It will get DONE, it won’t get halted because of distractions.
  • No need for dead-boring reviews, updates, more reviews, …
  • All team members get educated on all the changes in the sprint
  • It’s actually quite fun!

Try it in your teams and let me know how it worked!