This past weekend, I was honored to host a small gathering of Agile coaches at my home. Our conversation varied over many topics and I’ll be covering some of them in the upcoming days. The first I would like to cover came from a comment that Christian Gruber made. In the Agile Software Manifesto there is the statement that we value “working software over comprehensive documentation” and in the Agile Axioms we say “we are creators”. These two statements are closely related.

The comment Christian made was roughly as follows (and I’ve inserted a bunch of words to make the context clear):

When we communicate through documents in large organizations, there is often no specific person that is receiving the document. Rather, the document is being written by a role for a role both of which are part of some corporate process.

Since both the writing and receiving are being done in relation to abstract roles, the document itself becomes very abstract. The writer of the document must forget his or her humanity and write as a machine: precise, complete, making assumptions explicit, and carefully structured. In other words, write in a way which is very unnatural compared to normal human communication.

How do you feel when you read such a document? Bored? Insulted? Frustrated? Turned Off? Resentful?

No wonder! It wasn’t written for you. It was written for the least common denominator of you, namely, the role you play in an organization. This is dehumanizing. It is an attempt to make the people in an organization predictable and robotic in their communication.

So, in order to change this, Agile methods encourage that we write the least possible amount of documentation (not none). I would add, that when we must write documentation, we write it to a specific person. We find out who will be reading our document, get to know them at least a little bit. Then, write it with their name in it. Write it as an extended conversation. Make assumptions about what that person knows. Put your own personality into it. And of course, put in the crucial information. After all, you are writing for a reason 🙂