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"
or
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"
or
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: SOA, Service Architecture

Non-Principles

Okay so I talked about Anti-Principles so now I thought I'd talk about the final thing I list to list out in the principles sections of the projects I do. The non-principles this might sound like an odd concept but its one that has really paid dividends for me over the years. While Principles say what you should do and anti-principles say what you shouldn't the non-principles have a really powerful role.

A non-principle is something that you don't give a stuff about. You are explicitly declaring that its not of importance or consideration when you are making a decision.

While you can evaluate something against a principle to see if it is good or against a non-principle to see if it is bad the objective of the non-principles is to make clear things that shouldn't be evaluated against. In Freakonomics Steven Levitt talks about "Received Wisdom" and how its often wrong. I like to list out pieces in the non-principles that are those pieces of received wisdom and detail why they aren't in fact relevant.

Scenario 1 - Performance isn't the issue

A while ago I worked on a system where they were looking at making changes to an existing system. A mantra I kept hearing was that performance was a big problem. People were saying that the system was slow and that any new approach would have to be much quicker. So I went hunting for the raw data. The reality was that the current process which consisted of about 8 stages and one call to a 3rd party system was actually pretty quick. The automated testing could run through the process in about 6 seconds with 5 of those being taken up by the 3rd party system (which couldn't be changed) in other words the system itself was firing back pages in around 125 milliseconds which is lightning quick.

So in this case a core non-principle was performance optimisation. The non-principle was

"Any new approach will not consider performance optimisation as a key criteria"

This isn't an anti-principle as clearly building performant systems is a good thing but for our programme it was a non-principle as our SLA allowed us to respond in 3 seconds per page (excluding that pesky 3rd party call) so things that improved other core metrics (maintainability, cost of delivery, speed of delivery, etc) and sacrificed a little performance were okay.

Scenario 2 - Data Quality isn't important

The next programme was one that was looking to create a new master for product and sales information, this information was widely seen as being of a very poor quality in the organisation and there was a long term ambition to make it better. The first step however was to create the "master index" that cross referenced all the information in the existing systems so unified reports could be created in the global data warehouse.

Again everyone muttered on about data quality and in this case they were spot on. The final result of the programme was to indicate some serious gaps in the financial reporting. However at this first phase I ruled out data quality as being a focus. The reason for this was that it was impossible to start accurately attacking the data quality problems until we had a unified view of the scale of the problem. This required the master index to be created. The master index was the thing that indicated that a given product from one system was the same as one sold from another and that the customer in one area was the same as the customer in another. Once we had that master index we could then start cleaning up the information from a global perspective rather than messing around at a local level and potentially creating bigger problems.

So the non-principle for phase 1 was

"Data Quality improvement will not be considered as an objective in Phase 1, pre-existing data issues will be left as is and replicated into the phase 1 system"

This non-principle actually turned out to be a major boon as not only did it reduce the work required in Phase 1 it meant that the reports that could be done at the end of phase 1 really indicated the global scale of the problem and were already able to highlight discrepancies. Had we done some clean up during the process it wouldn't have been possible to prove that it wasn't a partial clean-up that was causing the issues.

Scenario 3 - Business Change is not an issue

The final example I'll use here is a package delivery programme. The principles talked about delivering a vanilla package solution while the anti-principles talked of the pain of customisation. The non-principle outlined however a real underpinning philosophy of the programme. We knew that business change was required, hell we'd set out on the journey saying that we were going to do it. Therefore we had a key non-principle

"Existing processes will not be considered when looking at future implementation"

Now this might sound harsh and arrogant but this is exactly what made the delivery a success. The company had recognised that they were buying a package because it was a non-differentiating area and that doing the leading practice from the package was where they wanted to get to. This made the current state of the processes irrelevant for the programme and made business change a key deliverable. This didn't however mean that business change was something we should consider when looking at process design. We knew that there had to be change, the board had signed off on that change and we were damned well going to deliver that change.

This non-principle helped to get the package solution out in a very small timeframe and made sure that upgrades and future extensions would be simple. It also made sure that everyone was focusing on delivering the change and not bleating about how things were done today.

Summary

So the point here is that the non-principles are very context specific and are really about documenting the perceived wisdom that is wrong from the programme perspective. The non-principles are the things that will save you time by cutting short debates and removing pointless meetings (for instance in Scenario 1 a whole stream of work was shut down because performance was downgraded in importance). Non-principles clearly state what you will ignore, they don't say what is good or bad because you shouldn't measure against them (e.g. in Scenario 3 it turned out that one of the package processes was identical to an existing process, this was a happy coincidence and not a reason to deliberately modify the package).

So when you are looking at your programme remember to document all three types of principles

1. The Principles - what good looks like and is measured against
2. The Anti-Principles - what bad looks like and is measured against
3. The non-principles - what you really couldn't give a stuff about

All three have power and value and missing one of them out will cause you pain.

Technorati Tags: SOA, Service Architecture