Are you guilty of the five deadly sins of technical writing?
Inspired by Amy Hoy's article - How Tech Writing Sucks: The Five Sins, I decided to put pen to paper, figurately of course. I loved this article. It's clear, amusing and sooooo relevant. I didn't think it was possible to use "suckitude" in a sentence but she nailed it.
Being one of the tech-writing sinners, I tried to identify why. Here's what I came up with.
1. Check box task
No-one ever reads the documentation unless there is a problem. As far as a decent sized stack of paper with some writing on it is delivered, the task is complete. Tick the check box. Only in some kind of emergency is the document dug out of some basement, the cobwebs blown off and actually read for the first time. Then the bombshell is dropped, it's completely useless. Meanwhile, some poor person's head is on the chopping block.
2. Defensive writing style
The actual topic requires one page. Covering every possible wrong turn, dead-end, cover my arse, etc. takes 50 pages. As I'm not an aspiring writer, why should I spend 4 days writing a document for a piece of code that took me 2 hours to complete? It's not a task I enjoy doing and it shows. I care more about my coding style, than my writing style.
3. Anal repetitive
If I’m aware that there’s a possibility that I could be sued for not stating what 'it' is, then I'll write documents that completely murder grammar. No definite or indefinite articles, pronouns, etc. Yuck, I know.
4. People do not compute
I spend my day either writing instructions for a machine, thinking about doing it faster with the minimum number of words, etc. This has also influenced my writing, I wouldn’t say I have a style even. So I frequently end up writing documents that don’t flow or read well for my target audience, the ordinary user but all my fellow techs get it.
I guess I need to practise more empathy, but I don’t actually know how an ordinary user thinks.
For example, it would never occur to me that someone would not know how to use a computer mouse.
I look forward to Amy's next instalment.