Practice3.Barely Sufficient Documentation

Practice 3. "Barely Sufficient" Documentation

In order for teams to concentrate on a working product, they should minimize the amount of time spent writing documents that are not part of the product. Examples of this type of document are requirements and design documents[1].

[1] Internal documentation is distinct from the external documentation that is included with the software. External documentation such as help and feature documentation is required by customers and should be considered as features. The intent of this practice is to minimize the internal documentation only.

Barely sufficient documentation is another important part of agile development. All too often, teams forget why they produce documentation: to produce a working product. In too many cases, documentation is required before a project can proceed to the next step. This introduces a linearity to development that is unhealthy and unrealistic. Many people lose sight of the fact that what truly matters in any development project is the process, especially the conversations and decisions required to produce a useful product. Documents are secondary to collaboration and learning and are a result of the process, not its focus.

This practice is intended to encourage teams to focus on what matters the most: their working products. If you have been involved in or observed a project where the team spent months or years trying to understand user requirements and writing documents without ever producing a product (or even writing any code at all), you'll understand the reasoning behind this rule! Customers don't know what they want until they see it; documents don't help customers at all.

Minimal Documentation and Code Comments

Some people carry the drive for minimal documentation too far. One example is code comments, where some individuals claim that code comments are superfluous because (a) when automated tests are present, code documentation adds very little and (b) most code comments are extra work that don't add value.

I think this is a dangerous attitude because good comments aid the understandability of code. Many of the best programmers I know write the comments first and describe the logic of what they are doing and then they write the code. So, while it's true that comments that state the obvious aren't valuable, it's important to not dismiss all comments.

Some of the barely sufficient forms of key documentation are:

  • The use of index cards for feature description in cycle planning. Index cards are used to describe features, to record the essential facts, and encourage team members to discuss the details. They also give team members something tangible to hold in their hands and quickly move around during planning sessions.

  • The collection of feature cards for a project should serve as adequate documentation of requirements. It may be necessary in exceptional cases to provide additional documentation, but these should be truly exceptional circumstances not the norm.

  • Design your software collaboratively in front of a whiteboard. Great discussions almost always result that highlight problems and alternative approaches. Then, simply take a picture of the whiteboard when done and place the image on a web page.

  • An alternative to drawing a design on a whiteboard is to use a sketching tool. There are some good inexpensive tools available, such as SketchBook Pro from Alias (

  • Put design details like relationships and code rationale with the source code (where it can be easily kept up to date) and extract them using a tool like JavaDoc or doxygen. This is a good practice because it encourages collaboration and decision making over document writing in addition to encouraging teams to get on to developing their product.

For details on designing software in an agile development context, refer to the section Simple Design in Chapter 6 on Design Emphasis.

The examples given above of barely sufficient documentation are by necessity brief and far from exhaustive. An entire book [Ambler and Jeffries 2002] has been written on this topic, and interested readers should refer to it for further information.

The Dangers of Excessive Documentation

I can think of two prominent examples of teams I have worked in that did not understand the practice of minimal documentation.

One case was early in my career where I worked at a company with a heavyweight development process. There was a rigorous process where for every feature we had to produce, in series: a requirements document, a functional specification, a design document, and written test plans. We had a large set of bookshelves where all these documents were kept. Review meetings were held for each document. It was amazing that we got any work done! We moved very slowly and wasted a lot of time writing, reviewing, and pushing documents around.

And some of our priorities were rather bizarre: I remember one meeting where there was a debate about whether we should use round bubbles or ellipses in design documents. And I'm sure you can guess how much these documents were consulted after we'd moved on to other features…!

Another example I can think of was a team that was charged with building a next-generation version of an existing product. There was a desire to build something different that would leapfrog the competition. This team spent six months trying to identify user requirements and designing what a next-generation product should look like architecturally. The result? A team leader, two senior software developers, two other developers, a user representative, and a high-profile customer produced quite a few documents and no code, not even a prototype, before the project was cancelled! That was a wasted opportunity, and a ton of wasted effort, and the need for the new product is still there today.

Sustainable Software Development. An Agile Perspective
Sustainable Software Development: An Agile Perspective
ISBN: 0321286081
EAN: 2147483647
Year: 2005
Pages: 125
Authors: Kevin Tate © 2008-2017.
If you may any questions please contact us: