Skip to main content

Thick as a brick

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

Post a Comment

Popular posts from this blog

new life for an old (FTX) PSU, improved life for one human

the LEDs on this 5m strip happen to emit light centred on a red that does unexpectedly helpful things to (and surprisingly deeply within) a human routinely exposed to it. it has been soldered to a Molex connector, plugged into a TFX power supply from a (retired: the MoBo is cactus) Small Form Factor PC, the assorted PSU connectors (and loose end from the strip) have been taped over. the LED strip cost $10.24 including postage, the rest cost $0, the PSU is running at 12½% of capacity, consumes less power than a laptop plug-pack despite running a fan. trial runs begin today.
Post a Comment
Read more

every-application-is-part-of-a-toolkit at work

I have a LibreOffice Impress slideshow that I wish to turn into a narrated video. 1. export the slideshow as PNG images (if that is partially broken — as at now — at higher resolutions, Export Directly as PDF then use ‘pdftoppm’ (from the poppler-utils package) to do the same). 2. write a small C program (63 lines including comments) to display those images one at a time, writing a config file entry for Imagination (default transition: ‘cross fade’) based on when the image-viewer application (‘display,’ from the GraphicsMagick suite) is closed on each one; run that, read each image aloud, then close each image in turn. 3. run ‘Imagination’ over the config file to produce a silent MP4 video with the correct timings. 4. run ‘Audacity’ to record speech while using ‘SMPlayer’ to display the silent video, then export that recording as a WAV file. 4a. optionally, use ‘TiMIDIty’ to convert a non-copyright-encumbered MIDI tune to WAV, then import that and blend it with the speech (as a quiet b...
1 comment
Read more

boundaries

pushing the actual boundaries of the physical (not extremes, the boundaries themselves) can often remove barriers not otherwise perceived. one can then often resolve an issue itself, rather than merely stonewalling at the physical consequences of the issue.
Post a Comment
Read more