I had the pleasure of spending some time talking about project management and software development with James Grenning, who was in town to do training for Object Mentor. (You can read his articles here.) We spoke about a wide range of topics, and I definitely learned a few things about code reviews, user stories and documentation.

James had some very interesting ideas. We spent some time talking about code reviews. He pointed out that when selecting code to review, it makes sense to concentrate on code that links objects together, rather than internal behavior of an object, since that’s what unit tests are for. That made a lot of sense to me — the unit tests Lose Weight Exercise the objects themselves, which means the risk of defects shifts more to the integration of objects. Targeting the reviews at the integration code is much more likely to catch exactly the sort of defects that unit tests would miss. (Note to James: I hope we get to see an article or blog entry giving us some details on this!)

The most interesting thing we talked about revolved around requirements gathering and XP user stories. I’ve long been of the opinion that while user stories can make good requirements gathering tools, they seem too temporary. They’re written on 4×6 index cards, and they never seem to be used again once the system is built. James pointed out that this is the point of user stories — they’re made permanent once they’re turned into acceptance tests. And then he said something very interesting: he pointed out that this eliminates the need to store redundant information about the project.

I think this is where James and I may have reached a disagreement. I think there’s a lot of value in having what might seem to be “redundant” information in different project documents. This is definitely counterintuitive for many programmers, since we’re trained to only store information once, and reference it rather than duplicate it. I think it’s very valuable to have, say, a rationale in a use case replicate some of the information that might be in the vision and scope document, or have a functional requirement mirror certain steps in a use case. Often, it’s useful to repeat a piece of information in order to make a requirement or use case more readable. And most of the time, that information isn’t necessarily redundant. A requirement may go beyond what’s written in the use case, adding information about how the software should function in order to implement it. When this requirement is reviewed, that extra information can provide a valuable quality check — if one of the team members has a misunderstanding in that area, it will make it likely that the two douments won’t reconcile with each other.

I think the basic principle at work here is that documentation isn’t created for its own sake. In some cases, like with user stories, the documentation is only an intermediate work product that leads to code and acceptance tests. Once those things are created, there’s no need to keep them around. On the other hand, project documentation like a vision and scope document or a use case has a different purpose: to make sure that everyone on the project team has the same understanding of what the project is supposed to do or how the software is supposed to behave. And, as we all know, while it’s more work to keep this sort of documentation up to date (through reviews, inspections and change control), this gives the team a lot of opprtunities to find and repair defects before they make it into code.