The AppLife Update Blog

  • The Past, Present and Future of Requirements Documentation

    Do you remember the days before Agile changed the software development discussion? Back before waterfall wasn't the term coined for all things bad about software development.  You should. It wasn't really that long ago.  Back in those days, believe it or not, there... gasp.... were successful software projects.  But how could that be!  Any time spent in today's software blogosphere would have you asking that question for sure. Successful projects have always been worked through some level of iteration. There just hasn't always been a recognizable methodology name for it.


    Back in those long lost days of yesteryear it would have been unthinkable to initiate a software project without any documentation.  Today, it seems almost unthinkable to document anything. Tomorrow, we think that today's experiences will bring about a resurgence of the importance of software requirements documentation.  These documents will not be created and managed like they were yesterday though. Iteratively creating and maintaining requirements documentation will be the way it's done.

    But what does it mean to iteratively create documentation?  Isn't all documents inherently created iteratively?  Iterations in requirements documentation are as much a mindset as it is an action. Its accepting the notion that documents are never finished, and that acceptance does not have to mean finalized.  Yesterday, a requirements document was written with the expectation of completion.  The document was completed when it passed a thorough stakeholder review.  Upon completion, strict change control was set in place, requiring the organizational equivalent of an act of congress to modify.  This type of requirements documentation is probably familiar to you, and it is not an iterative requirements doc. Authors of requirements docs that cannot be easily changed have an overwhelming burden to continue analyzing beyond the point of effective prudence.  These documents take a long time to "complete" and once completed, they are not maintained due to the organizational resistance to change.  These documents are often very expensive to create and filled with inaccuracies and bad assumptions. Instead of providing clear guidance, accurate estimates, and minimizing scope creep, they creating more harm than good.   This is precisely what has lead to the agile wave and a constant search for a better way.

    The "better way" is not to abandon documentation all together, as desirable as that may be to some.  Requirements communications always live longer than the verbal discussion they are born in.  If they are not captured somehow, problems later in the software development cycle will surely ensue.  If requirements documentation can be viewed as an iterative communications medium, a capture of conversation, and not a stone tablet, your documentation efforts will be worthwhile and lead to less scope creep, rework, and higher quality software.  Welcome to the future.

    Posted at 6 January, 2010 | By :Brian Haas | Categories : Functional Specs | Requirements Management |