Agile Value #2: Keep Documentation Light

Let's look at the next core agile value.

We value working software over comprehensive documentation

No amount of system documentation can compensate for a non-existing system. We can spend the better part of a projects life time writing specifications, discussing use cases and drawing designs charts without actually producing anything truly valuable for our customer. Working software is always more valuable than documentation and that is always the way we measure progress.

Not all documentation is bad, just that most of it is not really needed, and it is tedious to keep in sync with the actual software. Also, when documentation and implementation does not agree -- who is right?

Requirements

The classic requirements document is created through sweat, tears and lots of frustration. Frustration because it is a document predicting the future. If we predict the future wrong (which we will), it will inevitably cost us money, trust and maybe our jobs. Nothing good can come from this. 

Instead, things planned for the future should not be detailed at all and stuff that is nearer should be fleshed out more completely. When it is time to implement them, we should spend more time detailing them. This is the moment when we have as much information as possible, but not before that. This is called the latest responsible moment.

One way to think about it, is to imagine that you have all planned features laid out in front of you, from your feet towards the horizon. Items that are closer to you is more important right now and are seen clearly with details and everything. Things further away are a little blurred and only the title and some text is readable. Things even further away are so blurred that it is not possible to make out any details except the headline. When the nearest items have been implemented and the next features are shifted towards you, you can see them more clearly and you notice they are lacking crucial information. Now is the time to add more details.

Systems Documentation

Scrum and XP is based on the core agile values which is about preferring collaboration and working software before documentation and tools. It means that your time is best spent creating a shared understanding of the system design rather than writing detailed documentation. For this to happen, the team must talk about the design all the time; how to make the design better and how to adapt it to new changes. Constantly. All members in the team must be involved in the design discussions. Here are a few pointers:

• Don't write any systems documentation unless you have working code. Defer any such efforts until you have delivered your first incremental release. And as always, keep it simple!
• Draw an outline of the system so the team can easily to see how different parts are connected. This is the overview and should be pretty stable over time. Keep it up prominently on a wall.
• Locate your most important entity in your system (Order, Blog Entry, Transaction, ...) and create a state diagram for it. I have noticed that having the team create a few state diagrams helps their understanding of the system and they may even find a few quirks or bugs. Once the system starts growing, add one or two sequence diagrams showing a typical "request" through the system.
• Readable code without comments is what we are aiming for. It is much better to write clean code than copious amounts of documentation.
• I recommend adapting a mentality that considers every comment in the code as a personal challenge: Can I rewrite and clarify the code so the comment is not needed anymore?
• Use refactoring techniques with unit tests and don't be afraid to use longish function and variable names to make things clear.
  

I am going to write more about comments in a later post, so I'll leave that for now.