Saturday, April 24, 2010

Language in requirements, design and code reviews

Recently I've been doing a bunch of reviews in documents and other artefacts with multiple different groups of people and I've noticed a few things about what works when reviewing and what doesn't. I'm not talking here about the document format or the availability of tea but about how you review documents.

First off some ground rules, what I mean by this is that if you are in a key review position then you should be setting the expectations on what you consider to be good. So before people even start creating the stuff you are going to review spend 5 minutes with them just giving them some context on what you are looking for. This might be as simple as outlining where their piece fits into the broader picture or just making sure they have the right clarity on how they should be structuring what they have been set to do. This initial piece will save you a huge amount of pain later on.

So now when you get to the actual review you should at least be talking more about the content than wasting time telling someone that they've not created it properly and have to do some major rework.

So on into the review. I'm assuming here that you don't use design/requirement/code reviews to bollock people as that would be completely counter productive. If there are big issues pull them aside 1-on-1 later and have the discussion. So that said how to get people to learn from their mistakes?

The key here is language. There are some great phrases and some bad phrases. Lets say that someone has written something down that just isn't clear you can say

a) "This just isn't clear what you are trying to say"
b) "I'm confused around this bit, could you explain what you mean"

Now the former says "Crap work" the second says "Its probably me but lets just check" 9/10 times they'll explain in detail what they mean and you can say the magic words

"Great, now I understand it, you might like to write out what you've just said so no-one else gets confused"

Now lets say they've got something plain wrong you can say either

a) "That's just wrong"
b) "Umm what would the implications be if we do this?"

Then with b) you go into a discussion where you challenge them with points like "I see, but wouldn't X apply here?". This way you get to find out if its a mistake or they are actually a bit thick. If you do the former then you'll never get to know.

Now lets say there is an area where you realise that something you've done isn't clear and the person you are reviewing would benefit if it was clarified (for instance there is a diagram missing which would help explain their area). This is where you get to make the reviewee feel really good AND get work off your plate. The point here is to say something like

"I've just realised that I really should have created a diagram about Y by now as that would help you explain this area. I tell you what could you have a go at creating it and then we'll make sure that everyone sees it once we've got it right"

Here if you are a senior reviewer you are not only helping the person, and getting work away from yourself, you are really making the reviewee want to demonstrate that they can do a good job. That is the main aim with reviews. Catch the errors, help people improve and keep up morale. Kicking people in reviews for errors just doesn't make sense.

Pull the problems onto yourself, have the reviewee explain them and hopefully (if they aren't a muppet) they'll come to the right answer themselves, they'll think you are a great coach and they'll want to work harder for you.

The same does not apply to managers when reviewing project plans that are rubbish, they must be beaten about the head with a stick.

Technorati Tags: ,

No comments: