One of my pet hates in computer documentation is “thick as a brick” syndrome. One of the longest songs in existence this side of a Wagner opera is the extended version of “Thick as a Brick”, weighing in at over 43 minutes long. The key line in this song is: “And your wise men don’t know how it feels... to be as thick... as a brick.” Writers of documentation forget what it’s like to not understand the material they’re presenting, and consequently they make assumptions which are obvious to them, completely opaque to the student, and then build from there.
This is sad, ’coz they’re supposed to be the clever buggers, and yet they consistently do this really dumb thing. Worse, they often “solve” it by talking down to their audience... still without supplying the necessary context, much like a terroristtourist repeating his instructions to a local very loudly in the expectation that sheer volume will make up for a lack of comprehension.
The Sydney mentioned in my previous post has just run across one of these. He’s been given a subnet and instructed to place hosts within it, and also given an IP address for a DNS... but this address isn’t within the subnet, the server in the instructions is giving no sign of a second network card or other indication that it might be the gateway, and nor has he been given a gateway address for anything else. How does his traffic get to the DNS? D’oh?
When you write documentation, please don’t be as thick as a brick.
Comments