Thursday, May 7, 2015

Agile Principle Digging Through: Is Document still Valuable?

Build a good quality product and create sufficient documentation, but don't focus on making the document super flashy.

One of the important points in Agile Manifesto is "Working software over comprehensive documentation". So according to this, the product is given more priority than documentation, but do we still need documents? By stating explicitly that we value the working software rather than the documentation, we will now question whether the documentation is valuable.

Agile doesn't say “don't build documents.” It says priority is first a working software then you can document it. A flashy document doesn't replace a working software. Hence, most of the documentation that you traditionally created is "needed" because you discovered the information it contained a long time before you needed to use that information. If instead, you tailor the process so information is discovered or decided just in time for it to be used, then that information doesn't need to be written down except as the code or the tests for which you need to know those facts. Producing working software is a very preliminary requirement to a development team under any methodology: either Agile or waterfall and so on. There exist no methodology in favor of comprehensive documentation over working software. With respect to the question of documentation, the distinction is that when working very small fragments to completion, you can hold the information in the mind; it is created or discovered just in time, within minutes at most, to be used. It doesn't need to be recorded for use later. But there's a limit to how much you can hold in your mind current, before things start slipping out. If you try to work on larger chunks, you start to need to write things down.

Comprehensive documentation is needed, but you have to give priority to working software than documentation.The essence is that if you can create working software that the customer would value, do it. It's the best thing you can do. If you need documentation as part of what you do to create working software that the customer would value, then you would value that documentation. While Agile emphasizes on working codes and working software, and encourage small up front design, and design through evolution in iterations, It does not means rushing to coding with no design documentation. Comprehensive documentation means the documentation in Waterfall style. From a certain point of view, documentation in Agile should be more comprehensive, since the document is not so easily out of sync with the reality, as its waterfall counterpart did. For examples, user stories, issues, schema files, UML diagrams on paper or in modeling tool etc. are all documentation.

Sometimes the alternative (rediscovering if and when information is needed) is genuinely a more effective and efficient approach. These days the typical documentation is very slim and geared toward telling people who might need to reconstruct information where to start looking. That problem is usually owing to a lack of feedback - where developers don't get feedback on where they went wrong, they will get ever better at doing what they think is right without ever having the incorrect parts of their thinking challenged and improved. They get ever better at what they do, but they never get better at what they never do, and there are parts of the job they never do. While "working software over comprehensive documentation" is good against waste, the line of producing "enough" documents is whether the documentation helps developing "working software" and subsequent maintenance. Remember, no matter how smart and knowledgeable you are, or how many brain cells you have, your brain is still tiny in front of complicated problems today and complex structures you are going to build. Enough documentation in Agile forms is complementing our tiny flesh brains.

Build a good quality product and create sufficient documentation, but don't focus on making the document super flashy. Focus on making your software working well to satisfy customers. That's the essential of these Agile principles.


Post a Comment