Shibboleths of Technical Communication

A shibboleth is a test which separates friends from enemies, insiders from outsiders, the trustworthy from the suspect.

In medieval England, it was easy to tell the nobility from the peasantry: the nobility spoke French; the peasantry spoke English. This is why our words for meat on the hoof are Anglo-Saxon in origin (cow, sheep, pig) while our words for meat on the plate are French in origin (beef, mutton, pork). A peasant might steal a noble’s horse and cloak, but he could not pass himself off as a nobleman because he could not steal a noble’s tongue. read more

Is it Time to Quit Writing Tables?

Where have all the tables gone? Not that I miss them — I was never the biggest fan of tables — but there sure seem to be fewer of them about than there used to be.

Tables have been a staple of tech comm for a while now. Engineering documents have been full of them for many years, and Information Mapping encouraged their widespread use on the grounds that they stood out and made it easier for readers to find information in a sea of grey text.

I’ve never quite understood this point — if you are going to employ a device that encourages readers to skip the grey text and go straight to the table, why bother to include the grey text at all? But whatever: tables were hot. Now, it seems, they are cooling off rapidly. read more

What’s Hiding in Your TOC?

One of the defining characteristics of an Every Page is Page One topic is that it has no sequential or hierarchical relationship to other topics. There are no previous, next, or parent links in an EPPO topic, though there may be many links to topics on related subjects.

One of the objections I often hear from writers is that sometimes they need to create a defined order of topics because that set of topics forms a workflow. The question I ask in return is, if there is a workflow here, shouldn’t you have a topic describing that workflow explicitly? read more