Writing software with the grain

Exploring the humanity of Agile methods

1 2 3 4 Page 3
Page 3 of 4

Lightweight documentation

The Agile Manifesto famously prioritizes working software over documentation. Traditional software documentation usually goes unread because it is always out-of-date, doesn't compile, and is often among the most obtuse prose produced by the children of men. At worst it misleads those who do soldier through it and is a drain on the time of those who write it. This is not to discount the written word as a means of storing knowledge -- besides being wrongheaded, that would be a self-defeating point to make using written words -- but rather to establish the parameters of how we normally use writing within the human relationships in a typical software development team.

People who grow up free of certain disabilities always learn to speak the language to which they are first exposed. They never need lessons, don't appear to have to work at it, and learn the language more or less perfectly by about age 10. Not so with written language, which far from being a natural capacity is instead a learned technology. Almost no one learns to read and write without specific instruction. It's not hard for most people to pick up, but it is forced when compared to speech. The written word is a step less natural than the spoken word.

That said, human beings have taken to this particular technological form like ink takes to paper. Since the invention of writing, humans have produced mountains of text in a dizzying variety of forms. We write deeply important things, such as national constitutions, histories, and religious texts; and mundane things, like celebrity gossip and bills of lading. We write highly structured poems and highly unstructured stream-of-consciousness essays. Works of all types have survived writing's long history to give us a rich deposit of books to be read and studied, some thousands of years old. Through old books, we have access to millennia of accumulated knowledge and insight. In so many ways, writing is an unqualified good.

But how often do we read old books? For most of us, the answer (given with a tinge of embarrassment) is not often. This isn't because they're worthless, or don't have anything to say to us, or not necessarily even because we're lazy. Rather, it is because our default mode of learning new things relies significantly on people and things near to us. Academic and religious institutions can help with the important work of mediating old texts to contemporary readers. But other than that, most people are more likely to ask a question of someone they trust than they are to look to a Compendium of All World Knowledge for answers -- regardless of whether the people they trust are good sources, or if that Compendium had good answers in it all along. For right or wrong, when we have a question, we'd rather ask a member of the tribe than read the answer in a book.

Agile handles this tension responsibly. Recognizing the power of written language, Agile encourages us to keep written records of stories and even write the occasional spec document when the situation calls for it. However, in pushing for documentation to be lightweight and pragmatic, Agile explicitly recognizes that documentation is at best a reminder to have a conversation with someone we trust: a customer, a product owner, or a peer on the team. A properly functioning Agile team has no one canonical text to which a new team member can be directed to learn everything about the product; instead, the knowledge of the product is stored in the minds of individual team members. This approach has clear advantages and disadvantages, and different observers might come to opposite conclusions after weighing them carefully. Regardless of the outcome of that debate, it is clear that Agile's preference for storing knowledge in the tribe, rather than in long documents, is the more natively human approach.

1 2 3 4 Page 3
Page 3 of 4