Light But Sufficient


The theory so far seems to say that we should use a mostly oral tradition to bind the huge amount of information generated within the project.

Common sense tells us that oral tradition is insufficient.

Looking for Documentation

A programmer told of his company rewriting their current core product because there is no documentation, no one is left who knows how the system was built, and they are unable to make their next changes. He said he hopes there will be documentation after the project, this time.

Another told of three projects, each of which will build on the previous project. The three are not at the same location. He said that they can't possibly work on a strictly oral basis.


It is possible to have too little stickiness in the information at hand. It is time to revisit the Cooperative Game principle:

The primary goal is to deliver software; the secondary goal is to set up for the following game.

Reaching the primary goal is clear: If you don't deliver the software, it won't matter how nicely you have set up for the following game.

If, on the other hand, you deliver the software and do a poor job of setting up for the following game, you jeopardize that game.

The two are competing activities. Balancing the two competing activities relies on two arts.

The first art is guessing how to allocate resources to each goal. Ideally, documentation activities are deferred as long as possible and then made as small as possible. Excessive documentation done too early delays the delivery of the software. If, however, too little documentation is done too late, the person who knows something needed for the next project has already vanished.

The second art is guessing how much can be bound in your group's oral tradition and how much has to be committed to archival documentation. Recall that it does not matter, past a certain point, whether the models and other documentation are complete, correctly match the "real" world (whatever that is), or are up to date with the current version of the code. What matters is whether the people receiving them find them useful for their specific needs.

The correct amount of documentation is exactly that needed for the receiver to make her next move in the game. Any effort to make the models complete, correct, and current past that point is a waste of money.

Usually, the people I have interviewed on the successful projects felt that they had succeeded "despite the obviously incomplete documents and sloppy processes" (their words, not mine). Viewed in our current light, however, we can guess that they succeeded exactly because the people made good choices in stopping work on certain communications as soon as they reached sufficiency and before diminishing returns set in. They made the paperwork adequate; they didn't polish it.

Adequate is a great condition if the team is in a race for an end goal and is short on resources.

Recall the programmer who said,

"It is clear to me as I start creating use cases, object models, and the like that the work is doing some good. But at some point, it stops being useful and starts being both drudgery and a waste of effort. I can't detect when that point is crossed, and I have never heard it discussed. It is frustrating, because it turns a useful activity into a wasteful activity."

We are seeking that point, the one at which useful work becomes wasteful. That is the second art.

Barely Sufficient

I don't think I need to give examples of overly heavy or overly light methodologies. Most people have seen or heard enough of these.

"Just-barely-too-light" methodologies, on the other hand, are hard to find and are very informative. They are the ones that help us understand what barely sufficient means.

Two such project stories are given earlier in the book: "Just Never Documentation" on page 42, and "Sticking Thoughts onto the Wall" on page 128. In each, an otherwise well-run project ran below the level of sufficiency at a key moment.

Just Never Documentation (Recapped)

This team followed all of the XP practices and delivered software in a timely manner to a receptive customer. At the end of several years, the sponsoring executives slowed and eventually stopped new development.

After the team members dispersed, there was no archived documentation on the system and no team of people conversant with its structure. The formerly sufficient oral culture was now insufficient.


In this story, the team reached the first goal of the game, delivering a running system, but failed to set up for the next game, maintenance and evolution.

Using my own logic against me, one could argue that the documentation was exactly and perfectly sufficient for the needs of the company: The project was canceled, never to be restarted, and so the correct, minimal amount of documentation was zero!

However, drawing on Naur's "programming as theory building," we can see that the team members had successfully built up their own "theory" during the creation of the software, but they left insufficient tracks for the next team to benefit from the lessons they had learned.

Sticking Thoughts onto the Wall (Recapped)

The analysts could not keep track of the domain in their heads, it was so complex. However, they had just switched from a heavy process to XP and thought they were forbidden from producing any paperwork.

As the months went by, they found it increasingly hard to decide what to develop next and to determine the implications of their decisions. They were running below the threshold of sufficiency for their portion of the game. Rather than less, they needed more documentation to make their project work.

They eventually recognized their situation and started inventing information holders so that their communications would reach sufficiency.


What we should see is that "insufficiency" lies not in the methodology but in the fit between the methodology and the project as ecosystem. What is barely sufficient for one team may be overly sufficient or insufficient for another. Insufficiency occurs when team members do not communicate well enough for other team members to carry out their work.

The ideal quantity, "barely sufficient," varies by time and place within any one project. The same methodology may be overly sufficient at one moment on a project and insufficient at another moment.

That second art mentioned above is finding the point of "barely sufficient," and then finding it again when it moves.

Recommendations for Documentation

This leads us to a set of recommendations:

  • Don't ask for requirements to be perfect, design documents to be up to date with the code, or the project plan to match the state of the project.

  • Ask, instead, that the requirements gatherers capture just enough to communicate with the designers. Ask them to replace typing with faster communications media where possible, including visits in person or short video clips.

  • If the designers happen all to be expert and sitting close by each other, ask to dispense with design documentation beyond whiteboard sketches, and then capture the whiteboard drawings with photos or printing whiteboards.

  • Bear in mind that there will be other people coming after this design team, people who will, indeed, need more design documentation.

  • Run that as a parallel and resource-competing thread of the project instead of forcing it into the linear path of the project's development process.

  • Be as inventive as possible about ways to reach the two goals adequately, dodging the impracticalities of being perfect.

  • Find (using exaggerated adjectives for a moment) the lightest, sloppiest methodology possible for the situation. Make sure it is just rigorous enough that the communication actually is sufficient.



Agile Software Development. The Cooperative Game
Agile Software Development: The Cooperative Game (2nd Edition)
ISBN: 0321482751
EAN: 2147483647
Year: 2004
Pages: 126

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net