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.
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,
We are seeking that point, the one at which useful work becomes wasteful. That is the second art. Barely SufficientI 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.
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.
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 DocumentationThis leads us to a set of recommendations:
|