So-called heavyweight processes in software development prescribe large volumes of documentation. The proponents of agile processes (formerly called lightweight) call this defensive, and try to be open and honest in the relationship with the customer instead, so that there is no need for documents to serve as proof of decisions made whenever there’s a dispute. Extreme Programming, for example, doesn’t prescribe any form of documentation – but says that you should document only what the customer wants you to document.

I thought about this last night, as I have had a few occasions recently where a past decision proved to be wrong, and I couldn’t remember why the decision was made in the first place. On and off, I have kept lightweight notes during the project – first using a wiki, then a local weblog, then an OmniOutliner document – and I thought about making this a more regular practice, so I could go back and see why a decision was made.

Now, the project I am in definitely qualifies as one where the communication is open and honest. As we have realized that a past decision was wrong, none of us have dwelled on the question of why that decision was made in the first place. Instead, we have treated them as new features to be implemented. After all, what’s the use of arguing about such things? Our project is very much one where things were vague at the beginning, and where we constantly have explored what the system should do.

As I thought about this, I couldn’t see the need to document decisions. The code is there and is supposed to be well-factored and ready to absorb any future changes – so even if a new feature actually is a past decision that has been reverted, the code doesn’t care.

I thought about whether there are irreversible decisions, that once made cannot be altered. If there are, such decisions should be discovered early on and recognized by the members of the team as being irreversible. In my project, I can’t think of any irreversible decisions. There are definitely things that could take a long time to implement, that perhaps could have been done more quickly at an earlier stage – but they aren’t by far irreversible.

(As I wrote this I thought about a project a friend of mine was in, where changes had to be analyzed and documented first; then the affected documents were given revision numbers that indicated that they weren’t yet approved. After they had been approved, the task of implementing the changes was assigned to one or several programmers, as well as scheduled for test, et cetera.)

My conclusion is that, in agile projects, there’s little need to document decisions, but it’s important that those involved understand that for each feature that is discussed, there are as many interpretations of that feature as there are people in the project. By frequently releasing new versions for the customer to test, such misalignments are quickly uncovered – and then it is of little value to anyone to argue about someone not having understood correctly. As the system begins to take shape, there will always be past decisions that are realized to be wrong – but that’s just a matter of newly-thought-of changes. The past isn’t interesting. There’s only now.