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.

It’s quite possibly something that’s specific to the company I work for, because several of the recent imports have asked “where’s the rest of the documentation?” and complained when told “No, that’s all of it”. Which is fair. It means they have to go through the code to deduce everything. Sure, it’s possible, but it’s even worse than reading a tome (though it’s at least guaranteed to be up to date!) because code is written in such fine detail, that it takes a long time to understand anything. I remember watching a video of Linus Torvalds doing a talk (possibly his talk at Google about git?) where he mentions that code is an extraordinarily bad way for a human to communicate with another human, purely because code is fundamentally written for a thing which will blindly execute instructions nick-named things like “Halt and catch fire”. The problem with computers is that they do exactly what you tell them.

Now, I don’t want to devolve into a blog writer who hands down The Gospel According To Me, so I encourage you to challenge my musings in the comments. And here’s the reason for that preface: Documentation Sucks. Most of the documentation I’ve ever read was written for the author. It feels like it was written separately from the code and turns out to be little more than a description of it (as opposed to the reasoning behind the decisions made). It tends to rot much faster than those bits which have fallen off the end of the register into the bucket.

Which has eventually helped me back to the thing I started to write about initially. Communication is two-way, you can’t send and receive at the same time, but both must be supported and, most critically, the communication has to be in a shape that the receiver can deal with. The data not only needs to be in a form which is understandable by the recipient (wenn ich dieses Post auf Deutsch schreiben waere, dann waere es meistens fuer euch nicht verstandbar) but of a reasonable size. Providing an overwhelming (but complete) set of data is almost always much worse than providing no data whatsoever. Performing the slightest analysis can often turn the data into information, with more and more effort required to move up the triangle.

What we technical folk often don’t realise is that these very same mathematical concepts apply equally well to everyday things like speech and email. I am witness to far too many emails which provide a lot of details, but say nothing; the author believing that his audience, also being technical folk, care so much about the detail that the main concept becomes secondary. Details lead to meetings. Succinctly made points lead to things getting done.

But I worry now that in my effort to avoid a soliloquy I’m drifting dangerously close to ranting, so it’s probably time to sum up. Or as close as I can still manage. I don’t like 90% of the documentation I’ve ever read because I have to wade through so much data to get to the information. I’d much rather interact with something, of whom I can ask questions and prod when I don’t agree with the decision making process, watching them squirm a little – a little dose of Schadenfreude every now and then does the soul good. Hopefully making them teach me the documentation will make them write better stuff next time around, but I doubt it will work that way – everyone’s questions will be different. So until we are able to write documents aimed at group of individuals (not an individual group!) it will continue to suck and I will hate it. Yes, I’m getting in early at being a grumpy old man.