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.

Agile Value #1: It's All About Communication

Traditionally, your project methodology contains a huge pile of rules, procedures, documents and regulations for the team to follow. Those rules are there to instill a (false) sense of safety and control and to compensate for poor team communication and lack of trust.

Using agile methods turns this around completely, and that is also why it works so well. Nothing else comes even close to the power of using agile correctly, at its simplest and most powerful -- the so called core of agile. The core of agile consists of a couple of values and begins with:

We value individuals and interactions over processes and tools

What this means is you should be as light as possible on the ceremonies in your project and trust the team to do its job without resorting to procedures and rules. The goal is to improve communication within the team and to make them grow together and work better. So just remove anything that impedes communication between team members. It's as simple as that.

We want agile to be easy and pragmatic, so lets transform the abstract value into a list of practical things you can immediately start doing to gain a huge performance boost from your team today:

• Everyone on the team should sit together in the same room. No more walls between team members. This improves communication and makes everyone in on the project buzz and latest changes.
• Always prefer face-to-face talks instead of writing e-mail or chatting. It is known that 80% of communication is lost when done in writing. So talk to the person directly instead of wasting valuable time sending primitive messages back and forth.
• Make sure everyone is part of the team. This includes designers, customers, product managers and testers as well.
• Start work in pairs on one computer and switch pairs daily. It is the best way for skill transfer and practical learning. It also improves code quality, lowers bug rate and increases team performance. Not to mention that it is fun and rewarding! Working in pairs also removes the need for formal code reviews and lengthy documentation as it makes everyone feel responsible for all parts of the system. It is our code, not mine or yours. 
• Get rid of your work item/todo/tracking management software and start using paper cards and whiteboards instead. This encourages the team members to gather around and having discussions when and how to do certain things. It is also easier to prioritize and group the work in whatever way you want. Just by placing paper cards out in a row on a big table invites great discussion and participation from the team.
• Use walls and whiteboards to track status. It should be possible to see the current status of the team just by quickly glancing at the walls. Mark (or move) finished items from "in progress" to "completed" and plot the teams velocity on a big visible chart.

As you see, all this works towards improving communication between team members and increase  shared knowledge, which is exactly what the first agile value is all about.