The Failure of Language as Description

Posted on 24 February 2013 by Joseph

Last night, I sat down to play yet another round of my favorite board game, Settlers of Catan. As is pretty common, there was a newcomer who had never played before, and a couple players who needed a quick refresher. For some reason, it's usually my job to explain how the game is played, and I dutifully sat with a copy of the instructions (so as not to miss anything), explaining resource production, turn structure, various special cases, a little strategy, and other such topics.

As my description became longer and longer, I found myself apologizing for the ostensible complexity of the game. I assured the newcomer that the actual game itself, once play began, was much simpler and easier to follow than the instructions themselves.

This struck me as an interesting point, and as something that can be formulated in general: for some (classes of) things, the natural language description of the thing is significantly more complex than the thing itself.

On the one hand, this seems to be a failure of language. If language is purpose-built as a descriptive mechanism, then an inability to describe something effectively is by definition a swing and a miss. On the other hand, this can be seen as a triumph of the usability and power of the thing being described. If its purpose is so obvious as to not require description, yet so powerful that it defies description, then the thing has met its purpose beautifully. (Sidenote: I would definitely say this applies to Settlers).

I think that the above is also very pertinent to software and software documentation. The best software is intuitive and easy to use; documentation for the same software tends to be a long-winded, laborious combinatorial explosion of the different use cases and features. Since, as above, the software itself may already be a triumph, perhaps the best way to achieve parity with the documentation is to improve the descriptive mechanism.

Screenshots and videos are one way to improve the language of software documentation. Another is adding a layer of structure atop the description in order to make it more targeted and accessible. In a nutshell, this is one of the goals of Silvi: to elevate documentation to the level of what is being described, reducing the confusion of newcomers and the frustration of reference-seekers.

comments powered by Disqus