This post is part of a series in which I address Bill Miller’s criticisms of agile. Please read the original post for context. In this post I take on his criticism of the role of documentation in the agile process.
Here’s Bill’s criticism of documentation:
Traditional practices often go overboard in requiring documentation, often producing many pages no one ever reads or uses. That needs to be corrected. The Agile proponents promote oral communication over documentation. Oral communication is vital. There is nothing like the fidelity that can be had in a good conversation and it saves time. However, there is tremendous value in formal communication – especially having written requirements. Documentation frees people’s minds for new information. Memories often fail and people never remember every detail quite like it was intended. Put two or more people in a room to agree on requirements, and each will remember some of the details of the requirements differently. Further, formal requirements allow other people to review the details and provide further input. Reviews are a best practice when done intelligently. There is no opportunity for review without a written record.
This is an easy criticism to counter: Bill Miller simply misunderstands the role of documentation in agile.
First, let’s start with the Agile Manifesto. The only principle of the Agile Manifesto that could even conceivably address documentation is the following:
The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
Hm, nothing in there about verbal-only communication.
Next, let’s look at the history of the Agile Manifesto.
The Agile movement is not anti-methodology, in fact, many of us want to restore credibility to the word methodology. We want to restore a balance. We embrace modeling, but not in order to file some diagram in a dusty corporate repository. We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. We plan, but recognize the limits of planning in a turbulent environment. Those who would brand proponents of XP or SCRUM or any of the other Agile Methodologies as “hackers” are ignorant of both the methodologies and the original definition of the term hacker.
There’s a little more specificity, but again, it doesn’t mandate no written documentation. Quite the opposite; it ’embraces’ useful documentation.
Enough about theory. Let’s look at the documentation on my most recent scrum team. We produced the following:
- Requirements in the form of user stories with acceptance criteria
- Design requirements in the form of UI mockups
- Functional specifications as wiki pages
- Test cases and execution results in SilkCentral Test Manager
- Defects logged in SilkCentral Issue Manager
- End user documentation for the product we were developing
The main point is that we always asked ourselves if we had enough, but not too much, documentation. Did we have what we needed in order to develop our product, and did our documentation leave an adequate trail for those who work on this project down the line?
Another salient point is that our documentation was in known public (within the company) places: in management tools or on the wiki. Not only did we minimally document our work for posterity, but anyone in the company could see our documentation at any time.