Friday, November 12, 2010

On Communication and Documentation

East is East and West is West
And Ne'er the twain shall meet.

Kipling knew more about developing software than some people I can think of, or have worked with on occasion. 

I had a conversation this week that reminded me about good ol' Rudyard's poetry.  I was talking with some folks I know and they were rather muttering about how they can't get questions answered.  The funny thing is I've had conversations like that before.  They all go something like this:

Me:  "Hey, I've have a question about HIJ function in XYZ project."
Them:  "The detail design has everything in it."
Me:  "OK, well, I read that and the requirements doc and I'm still not sure about something."
Them:  "The detail design doc has all the infromation you need."
Me:  "Well, I read that and there's a couple things I don't understand.  I wonder if we can talk about them."
Then: "We don't need to talk.  Everything is in the documents you have.  There's no room for questions."


Dear people,

Documents should assist communication, not replace it.  Communication involves more than writing, or reading, a document.  Since not everyone shares the same world-view, it seems that sometimes, when someone writes something, other people read it and may not understand completely.  How can that be if "Everything is in the documents?" 

Maybe it should be "Everything I think you need is in the documents."  I'm not sure. 

It always strikes me that the point of "Communication" is something that got talked about when I was taking classes an eon or two ago.  I learned that communication is a process of transferring information from one person to another.  I don't recall anything about "documents." 

Now, don't get me wrong.  Documents are great!  I've written some myself!  I have read many of them written by other people.  The point of it is that the information should be conveyed between people.  Documents can record decisions.  Documents can support conclusions.  Documents can serve as memory aides.

Documents are not, in themselves, communication.  Just like East is not West. 


  1. Yes, I've experienced those types of reactions to questions.

    If I have a question and someone points to a document (that I've read) it means my interpretation is different from their intended interpretation - i.e. their were no interpretation notes. When I remind them of this there's usually a softening of attitude.

    I like Tor Norretranders view on communication - that there's a type of handskaing (protocol even) between a sender and receiver before communication flow can happen (it's the same in machines and humans) - i.e. the two parties (or more) are establishing a context in which communication can happen.

    If anyone thinks they can achieve this in a document than "you're a better man than I am Gunga Din" (to quote Kipling)!

  2. Agreed, Simon. I like the handshake analogy, too. What happens too often, and partly prompted me to write this, is that some folks fail to see the need for opening channels so that communication can happen.

    Thanks for the commnet - and keeping the Kipling thing going!


  3. Nice post Pete, like yourself I'm surprised at how often this fact is ignored. Myself I hate the idea of excessive documentation in any form which expresses something that could have been communicated clearly and easily.

    All documentation is fallible, consider that. Its true written communication is so easily misinterpreted. Some of the best communicators I've met often follow up anything they have written in a document or email with a verbal discussion; be that to an individual or group.

  4. Thanks, Darren - Isn't it amazing how this simple idea gets muddled up?