Tools for Disciplined Thinking
The is nothing in the manifesto that says we can’t write documentation if we think it’s a valuable contribution the the product. That line in the Agile Manifesto about working software over comprehensive documentation means is that we can’t use our documentation as a measure of progress.
Documentation says little about how the product is actually progressing.
That’s because documentation is a transient product. It’s an intermediate artifact of the software creation process, and not what our customer pays us to build. We get into trouble when we start thinking the project is 60% done because we’ve written a stack of design docs. Documents are full of assumptions and unrealized risk.
That said, I think my tolerance for documentation is higher than most… and certainly higher than that of many folks new to agile, and excited to cast off the chains of more traditional software development life cycles. Most of the time I have to convince folks that it is actually okay to write things down. It is okay to capture your thoughts on paper or in a tool.
Word documents can be okay… so can Powerpoint… and even <gasp> MS-Project plans. I’m even okay in some context with standard templates and checklists. Granted, not every project… not every team… needs this much structure. What I find though, is that many of the forms we used to fill out, actually contributed to the level of disciplined thinking.
Those forms gave us a framework for discussion, and a list of stuff that we probably shouldn’t forget to consider. Somewhere along the way… likely some project manager type … came along and lost sight of the goal. When templates were filled out, projects were more successful, so therefore the existence of the filled-out template must have been the reason why.
Somewhere along the way, the focus became getting the document filled out rather than the thought that went into creating it.
I’ve got examples of Marketing teams that use a MS-Project doc to guide their tradeoff decisions during sprint planning. I’ve got business analysts that use their traditional requirements format to guide their creation of the prioritized product backlog. I’ve got project managers writing vision documents and charters used to communicate project intent to their stakeholders.
In and of themselves, there is nothing wrong with these documents. There is nothing wrong with templates and checklists. The teams these folks work on are fully agile and using these documents for their intended purpose… to think through the problem and to document what they learned collaborating with their teams. The documents are not the end product, but a means to help us get to the end product.
Comments (6)
Agile Scout
Well said. Documentation definitely has it’s place. Some would say “work before paperwork” but in some Agile cases and definitely security reasons, documentation is a necessity.
Scott Duncan
This would have been really good even if you had stopped with the first 3 paragraphs as they nicely explain that second Value in the Manifesto.
That said the rest is, of course, good as well. The importance of “the thought that went into creating” documenation is, for me, especially relevant. Whether it is Agile or traditional projects I encounter, there is a strong demand for “templates” before there is understanding about what is being documented in the template.
I’d have to look it up, but somewhere recently I read the comment that, if you can’t be successful with cards (i.e., manually), (automated) tools won’t make it better. I’d say the same about documentation rigor.
Sameer Bendre
Thanks for this post, Mike. This all comes back to “How much is “just enough”. The problem being there’s always someone who will want ALL sections to be completed in the requirements document. Philosophy: We don’t want others who reference this document in future to think this/short form of document is a standard – They create the standards or organizational process assets for “CYA” reason. How do you suggest handling such thoughts or people with such attitudes?
Scott. Thanks for the comment. So many of the folks I talk to struggle to find an appropriate way to capture their ideas on complex products. They think the only thing available to them is a 3×3 sticky note ;-) The trick is to figure out how and when to write stuff down without it becoming locked in stone.
Create safety. But creating safety is non-trivial in these organizations. If the organization has a CYA culture, that will take a while to change, but you hope frequent delivery will help.