My Ten Tips For Technical Writing

I have written many hundreds of thousands of words over my career – not only work product, but books, trade publication articles and so on. Over that time, I’ve read far more then I’ve written. And in that time, I’ve slowly developed a set of rules for how I write. Or for how I hope to write!

In my career, I have had three great writing mentors: Keith Burgess, Roy Chapman, and Susan Greenberg. Keith was a partner at what was then Arthur Andersen Management Consultants who I worked directly throughout my time there (and was to work for again 20 years later). I did work for Roy over the years, he was a master at writing. Susan Greenberg was an amazing instructional designer at Microsoft and a great teacher. All these people strove for excellent writing – and each helped me to learn to write better.

My ten rules are really pretty straightforward. Some can easily be converted in to muscle memory – your hands just type better text. And when I see some of my rules broken in other people’s writing – it drives me nuts. Those authors who have had me as an editor will recognise some of them!

So here are my ten rules for better writing:

1. Avoid future tense  This rule has a couple of benefits. Some languages deal with future tense differently to English – present tense is easier. Also future tense may make the writing harder to understand. For example: if you say “clicking on the foo button will make bar happen”. So the question is when will that happen? Is it immediate? Will bar happen in a minute/hour/day? Better to say: ‘Clicking on the foo button makes bar happen.
2. Avoid passive voice Passive voice is, to cite Wikipedia,a grammatical construction where the noun that would be the object of an active sentence appears as the subject of the sentence.  Active voice, for example “Our company builds the best widgets whilst in passive voice it’s “The best widgets are built by our company. Sentences with passive voice add words to the sentence (6 vs 8 words). They can also make the reader work harder to understand the intended meaning.
3. No split infinitives Yeah – I know: To Boldly Go and all that.  But an infinitive is a single idea – splitting it makes understanding more difficult. You should avoid that.
4. What is it, so what  This is one of the lessons Susan Greenberg beat into me. It’s simple really: when you are writing about something, you should explain what it IS, before telling us why it matters. I really hate reading about some product or technology where the writer spends the first few paragraphs telling me why it was cool, without ever explaining precisely what ‘it’ actually is. Define your terms, THEN tell me why I need this product.
5. Organise carefully I learned this lesson watching Keith Burgess. When you are writing a client report, or a magazine article, you have a purpose. That purpose could be to justify a project, or to explain a product or product feature. You need to organise your thoughts carefully, progressing from premise through to conclusion. You are taking the reader on the journey. We all know authors who veer widely off topic with annoying regularity.
6. Decide on 2nd person vs 3rd person This is about how you are talking to the reader. Do you say: “You do X to make the Y feature work” or “The user does X to make the Y feature work”.  I prefer to directly to the reader, you, vs some one else, eg the user, the manager, the IT Pro. I like to talk directly to the person who is reading.
7. Gender neutrality - or not This is one where political correctness can abound. I see some writers trying to be cute and always using ‘she’, or ‘chairwoman, or those being politically correct, eg the chairperson. I have views here – but the level of neutrality you need will depend on the target audience. You do need to be sensitive to your audience
8. The Oxford Comma This one is subjective – some ignore it, others insist. It’s called Oxford comma because it was used by printers, readers, and editors at Oxford University Press. It can clarify the meaning of a sentence when the items in a list are not single words.
9. Be balanced I like to see the good news AND the bad news. Nothing I hate more than pure puff pieces – ones that just say good things about a product. Likewise, I dislike totally negative articles. I’ve prefer writers that see both sides, who are balanced in their coverage. NO product is perfect.
10. If you can't say something nice, say nothing at all  Rarely, but on occasion, I’ve had occasion to use this rule. I’ve been asked to write about products or technologies I just do not believe in. I’ve found it easier to just not write an article than write one that is just negative.

That’s it. Simple really!