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.