Writing in plain English

I've been creating quite a bit of documentation lately.  I try very hard to write good, clear documents without unnecessary detail.  (So that means not describing in detail, with screenshots, every input box on a straightforward authentication dialog in a document aimed at desktop support people.  If your support teams need that level of help, I hate to be the one to break it to you, but you have problems that no amount of documentation will fix.  But I digress...)

Recently I was asked to translate a fairly technical description of a problem into something a less technically-minded person could understand.  In fact the brief was "translate it into something your granny would understand" (a pretty tall order as neither of my grandmothers are alive, but I knew what he meant).

Thankfully this is something I've done several times before - usually the instructions are "translate it into something my MD will understand" but unless the MD in question has a technical background that usually equates to about the same.

Anyhow, had I found the task at all difficult, this excellent document from the Plain English Campaign would have given me some great pointers:

How to write in plain English

I recommend having a look around the whole site because it's entertaining as well as informative.  Us techies are infamous for being poor communicators so it does no harm to a) try to learn to do better or b) console ourselves that at least there are worse offenders and have a good laugh at their expense.

In fact I'm starting to think the document above should be compulsory reading for anyone who ever went to university.  I've no idea how it happens (I left school at 18 so I'm in the clear), but somewhere between school and the workplace people stop writing "we did the experiment and wrote down the results" and start coming up with strange constructions like "a manual recording and collation methodology was employed in order to compile a dataset for utilisation in analysis of the observations resulting from the application of the prescribed experimentation procedures".  (I made that one up, but if you look around on the Plain English Campaign site you'll see it isn't that far-fetched.)

I plan to follow up with a handful of posts about writing technical and user documentation... if I ever break off from writing actual documents long enough to write the posts, that is!