Getting things down: the case for documentation

Half way down the Agile Manifesto (a list of the principles fundamental to agile software development), it states “Working software over comprehensive documentation.”  I don’t know how many of us actually refer to the Agile Manifesto when we first get up in the morning, but I’ll bet quite of few of us have a gut appreciation for that sentiment. Many project managers and developers alike want to get things done more than they want to get things down.

In my view, this is happy path thinking. You may be able to skimp on the requirements documentation and do just a few use cases as long as you are working in close proximity to one another, with all the advantages that co-location provides. It can also work fairly well if you have a user representative participating in the service development with you. It also helps tremendously, of course, if you have a boss, or project sponsor, who never wavers in her or his support.

But let me introduce one variable into this happy world that changes everything: collaboration. That one factor actually brings with it a cascade of implications: distance (and time lags), virtual team members, more stakeholders, different work habits, organizational culture variations, and so on. So now, getting things down starts to take on an entirely new level of importance. Let me explain my thinking.

Collaborations vary, of course. Certainly one important decision is whether to divide up responsibilities or to try for a more integrated approach. Either way, the chances are very good that you will end up with some interdependencies. Interdependencies need to be made explicit in project planning in order to avoid nasty surprises. You do this by documenting the major milestones, the inputs, the outputs, the resource constraints, and so forth–essentially whatever it takes to expose the relationship between the parts to everyone’s satisfaction.

Equally, when you want to build or provide something together, you are faced with the challenge of how to reveal what is in your head to your partners. I suppose the first challenge, perhaps, is with yourself: will you reveal what is in your head? How much do you want to share with your new partner(s)? This is a question about the collaboration itself, isn’t it?

Let’s assume, though, that you believe in the big picture, the vision of how working together can change the landscape. Here is where writing things down really plays a crucial role. If you keep things undocumented, your partners have to interrogate you, have to seek each bit of information from you. You become, in other words, an information bottleneck.

Sure, it’s a pain in the neck to stop what you’re doing in order to describe what you have already done. But, remember that big picture? This is a good time to take a look at it. It turns out that sharing your ideas and your work by writing them down is between here and there. In the case of collaboration, the case for documentation comes down to that.