Intentionally bad

Have you ever encountered tasks or subjects that are are written about so badly or sparsely, you get the impression that it’s been done on purpose? I can think of two topic areas where the documentation fits this description together with some pretty good reasons why.

Gunpowder, treason and plot

Most people know the composition of gunpowder and the ratios of the mix aren’t too hard to come by. If you watch the news you probably have a reasonable idea of what goes into home-made high explosives... but that’s as far as it goes. Most descriptions of anything that goes “bang” are curiously short of a step by step guide to manufacture, whilst the literature that does exist seems subject to a campaign of nay-saying and warnings of disaster. The reason (of course) is that those of us who understand how these things are made would rather people who shouldn’t have explosives blew themselves up in their own garden shed when getting it wrong.

Hacking

Hacking is performed much like any advanced task on a computer. It’s not The Matrix, often it’s just a case of putting the right bits of SQL into a box on a webpage or working out that email addresses in a company follow a pattern (such as [firstname].[lastname]) and going through their login page one employee at a time to find the dude who’s been allowed to use 123456 or password for their login credentials. In a less than ideal world, admin@[company].com with an obvious password will exist with all the implied access. More advanced hacking (the kind that makes the newspapers) requires detailed knowledge of exploits and weaknesses in systems (that I don’t have) which are painstakingly researched and closely guarded secrets. Often tutorials on hacking stop just short of allowing the reader to do any damage, whilst most of what happens has no easily accessible knowledge base as it would allow software companies to conduct a bit of counter research and fix their products.

What are the implications for technical communicators from these two nefarious examples? Well, firstly, there is a rebuttal to the school of thought that says “share everything, and put it on the web“ – anything that gets released out the door should be vetted so that it doesn’t give away commercially sensitive details or allow harm to come to the organisation and its customers – this includes the habit that some software providers have of publishing their default admin account details and passwords in manuals available in soft-copy form without reminding (or forcing) their customers to change them. Somewhere, a customer will place these documents on an unsecured intranet, and that will open up a vulnerability for every client you have who hasn’t bothered removing or changing the default account settings.

Secondly, there’s the social proof provided by these well known examples... if products don’t have documentation, or if documentation is incomplete, there is a risk of damaging reputation because clients will identify the product with the dodgy, and one way or another they’ll trust you less than they should.

Andrew