Title: People of the .Doc

Author: Martin Moene

Date: 02 December 2014 19:26:07 +00:00 or Tue, 02 December 2014 19:26:07 +00:00

Summary: Technical communication is often misunderstood by the world at large. Andrew Peck breaks down the rhetoric from a technical author’s perspective.

Body: 

We are sometimes invited to ‘see ourselves as others see us’. This article takes the reverse viewpoint, seeing a group of people who often work alongside us through their eyes, not ours.

Do you find that your work is treated by friends and family as being a form of witchcraft? That’s probably because they’re in sway to Clarke’s 3rd law, which states that ‘Any sufficiently advanced technology is indistinguishable from magic.’ [Wikipedia]. Computers, IT professionals and programmers are often treated with a reverence once reserved for doctors and before that priests and shamans. The mystery is two fold: first any modern device or application is – from the perspective of the user – a black box into which they place input to gain a result. They have no knowledge of the intricately crafted logic that allows the most aesthetically simple device to function, and so they adopt the same attitudes we might associate with throwing coins in a wishing well... only the wishing well of IT often throws something back.

It’s not just the users and outsiders to blame for this of course. Computer systems are a mystery to the world at large in part because the majority of those who do understand them spend their working life surrounded by others who use the same jargon and do similar things, and so a closed community is created with knowledgeable insiders and unwitting outsiders.

I suppose this is where the technical communicator comes in. We are the deacons and evangelists of the church of high technology. Whilst linking to a blog post of mine, the Guardian technology team [Guardian] described us for the uninitiated as “the hapless folk who have to write the manual that you never read but which explains how it actually works”.

Let’s consider the accuracy of this definition and see if we can suggest an appropriate and approved alternative. Who knows, we may even get an amendment similar to those sometimes found in the cheaper tabloids when they get a footballer’s deviance à la mode wrong!

The myth

Having regularly endured a myriad of Christmas movies featuring animated and/or over-acted depictions of Santa Claus, when I read the description of the ‘hapless folk’, I’m put in mind of the elf who’s a little bit ‘different’, the one who is given some kind of make-work task because he can’t be trusted with anything that might do lasting harm if inserted up a nostril. I’m a little disappointed that the popular view of technical writing is of something that happens under duress, for ungrateful disinterested end users. There is also the implication that our writing is somehow pointless, as if the only thing this profession produces is badly translated hand-outs to go with cheap electronics.

The reality

Technical communication can be outwardly very dull, but it’s that way for a reason. I feel that as a general rule the more exciting, world changing and expensive the product, the more structured and precise any accompanying documentation becomes (imagine the precision needed in the manual for an anti-tank munitions). The reason for this of course is that the more fantastical the product, the greater the cost and damage done if something goes wrong and that is essentially where we come in. If ‘tech-support’ is the cure, we are the prevention that is so much sweeter. It is frustrating to have to have to use the same lexical chunks within a piece of writing, but we are shoeing the technological horse, and florid patterns aren’t really of much use to users, translators or localisation teams. (We can save these for other types of writing... in this article alone you'll find anglicised French, Latin and a parody of Islamic theology – none of which would be encouraged in software documentation.)

That’s not to say that we’re in any way less skilled than our counterparts who write in different ways for different purposes. The novelist or journalist may get away with ‘typing’, but we are master-users of desktop publishing, word processing and authoring software. I haven’t used the buttons in Word’s ribbon for ‘bold’ and ‘italic’ in a decade, and even the keyboard shortcuts find their outings cut short due to the catalogue of carefully constructed and balanced styles that have documents parading past a client’s eyes like an old school soviet military parade.

Based on the above, the definition that I’d like to see in the public domain would be something along the lines of ‘the professional specialists who make complex products and procedures clear and accessible to the rest of us’. Accessible documentation is as important as clarity, people should be able to find what they need to know when they need to know it.

Our responsibility ends once a high quality message is out there; if people choose not to read the manual, and as a result shut down a stock exchange, shoot themselves in the foot or put their furniture together upside down there’s not a lot we can do about it.

The dream

The above definition is quite accurate, and I’d encourage anyone who’s every wondered ‘is this a career for me?’ to think very carefully about the unique set of skills and traits they’ll need to develop. As a reward, I can promise that no one is going to wrap fish and chips in what you write.

If there is a Deus ex machina (a term from literature meaning ‘God from the machine’) we technical communicators are the prophets, scribes and high priests of the ‘People of the Doc’.

References

[Guardian] http://www.theguardian.com/technology/blog/2013/jan/07/technology-links-newsbucket

[Wikipedia] http://en.wikipedia.org/wiki/Clarke%27s_three_laws

Acknowledgements

This article is based on one previously published in Communicator (Spring 2013), the journal of the ISTC (www.istc.org.uk).

Notes: 

More fields may be available via dynamicdata ..