Mistrust in Applicability: Documentation

Overview

Agile software development often sounds so simple that many people cannot believe it will work. The typical reaction to mistrust in an approach is to ask the team to deliver a set of defined artifacts or to use some distinct tools. In all honesty, we know that everybody can produce almost any artifact other than code or use any tool. However, the artifact’s production or the tool’s usage is not a sign that the system has reached a specific status. The only sign which leads to this conclusion is working software.

This section focuses on two kinds of techniques:

• First, we discuss techniques often used to overcome mistrust in processes and teams.
• Second, we discuss techniques that are quite common in agile software development but often lead to mistrust in nonagile environments.

Documentation

There is a myth that some agile methodologies regard documentation as being evil. This may stem from the “Agile Manifesto” value of “working software over comprehensive documentation.” This has sometimes been interpreted to mean that nobody who follows agile methodology documents a thing. The truth is, documentation is considered very carefully in an agile methodology, especially when compared to a more document-centered methodology. Therefore, current documentation has to be thoroughly examined.

The documentation we find in most nonagile projects is write-only. Write-only documentation is easy to spot: it looks very accurate, stays on the shelf, and has no coffee stains on any page. This is a clear sign that nobody trusts it. This is understandable. Documentation is not executable and therefore not testable. Therefore, it is hard to judge if it describes what we are looking for.