Communication is half-duplex

Communication.  It’s something that we technical folk are traditionally un-awesome at. Sure, we can do things like read Strunk and White to make our blog-writing better, which fits nicely into our world view. Those two guys have provided a succinct set of technical rules, with examples and counter examples, on how to write well england. Which is great. The least effective method for communication is now a solved problem. Hurray. Blogs, however are clearly a better method for communicating things, well ok, slightly better – because they at least have a comments section where, given enough eyeballs, all misunderstandings become shallow. Or you eventually get to arguing about Why Hitler Was Bad.

So why is Documentation hallowed as so necessary and important, if reading it (often far removed in time, space or both from the original author) is such a terrible way to gain understanding? Sometimes I read documentation. But mostly I only read a small portion of it. In almost all circumstances, I’ll go and talk to an actual person who I know to have been in that portion of the code. The document I have referenced most in the current company I work for is the definition of a protocol. Not a design document. Not a UML diagram suggesting the structure of the code base. A protocol. And I look at that the most because I periodically have to pick apart a stream of it to figure out where a bug is hiding.

Read more of this post