This morning, I was looking through one of the stack of trade magazines that seems to find its way to my mailbox and read a very interesting article on software documentation that I wanted to share with you. In the article, (“Documentation Strategies” by Scott W. Ambler, in the March 2007 issue of Doctor Dobb’s Journal), the author reiterates that “ documentation is an important part of every system, regardless of the paradigm followed to develop that system.” Figuring out where to strike a balance between having sufficient documentation vs. not spending too much effort on documentation (vs. coding) is one of the things that most development teams, whether agile or traditional, struggle with – and is one of the key areas that the RM teams struggle with as we try to define a consistent set of deliverables (release criteria)  to be used by teams developing software for our operational environments.

Ambler suggests that system documentation should  be treated like any other requested feature – “What you do is suggest to your stakeholders the need for such documentation, justify why it’s important, estimate the Total Cost of Ownership (TCO) of creating and maintaining it, and then let them decide whether they wish to invest in the documentation.”  This approach is markedly different than the one taken by traditional software processes – which, as we have all experienced, often lead to “overly bureaucratic and documentation-heavy processes” that are often justified by regulatory requirements. When this is the case, Ambler points out, one of the key steps is “to ensure that your resulting process is as streamlined as possible yet still in compliance.” Sounds familiar to me… J

He also suggests that documentation should be created when it’s needed, and only if it’s actually needed – noting that sometimes, there are alternatives to documents. For example, many times it’s possible to use a suite of user acceptance tests in lieu of a specification.

The article also gives a number of pointers to further information about agile documentation, which has become really important to me lately as some of the project teams I'm on have begun to use Scrum... but more on that in another blog post later.