Lightweight Documentation… Not Lightweight Thinking

Working software over comprehensive documentation… this line in the manifesto has been used to justify all manner of undisciplined thinking over the years. Just because we value working software over comprehensive documentation, doesn’t mean we don’t ever write anything down… and it especially doesn’t mean that we don’t think through problems. It doesn’t mean that we don’t do the discovery, analysis, and design that often was captured in all that comprehensive documentation.

The problem with comprehensive documentation is that it is a poor communication tool for helping developers understand the needs of the customer. It’s a poor communication tool for explaining to a team of developers how to build a product. It’s a poor predictor of what the product will even do when it is done. Documentation is essentially a transient artifact, intended to keep a record of decisions and communicate intent.  Far too often it’s used as a primary measure of progress… especially in the absence of incremental delivery of working software.

In more traditional environments, people are tasked to create some sort of a requirements document, or maybe a design document or a project charter. Somewhere along the way, many folks start to think that the mere presence of the artifact is all that’s required to build software. The document becomes an end unto itself. It’s not the document that’s important… it’s the shared understanding that came out of creating the document that’s important. The document is simply an artifact representing that shared understanding.

Six or seven years ago I was mentoring a junior Project Manager that was struggling to create a project charter. I sat down with him and started asking him who he had met with, what was his understanding of the goals and objectives of the project, and what he knew about the assumptions, risks, budget, and expectations surrounding the project. His response? I haven’t met with anyone… my job is to write this charter. He somehow had come to the conclusion that the mere presence of a charter was the end goal.

Yes, his job was to write the charter… but ONLY after he facilitated the discussion that generated the shared understanding that was to be written in that charter.

Many folks new to agile feel like they no longer have permission to write stuff down. I encourage them to write down whatever they need to write down, but not to think of the document as the deliverable, think of the document as a record of an agreement that we want to track. Maybe a tool for thinking through a problem.  If you want to use a template or a form to help yourself think through all the things you may want to consider while decomposing the problem… that’s fine. Use documentation as a record of what has been created, rather than a prediction of what should be created.

At the end of the day, documentation does not reduce risk or validate assumptions, and no amount of documentation is a measure of progress on our project. But just because we do lightweight documentation doesn’t mean lightweight thinking… we just want to do the simplest thing necessary to facilitate shared understanding of the emerging product we are trying to build. Shared understanding of the problem, and agreement on how to proceed, is what we are going for. Documentation is never a goal unto itself.

That is why we value working software over comprehensive documentation.