Make it snappy

When you’re a technical writer being told that your writing is “dull”, “boring” and “full of platitudes” is the kiss of death. It’s even worse when you don’t disagree.

I’ve been reviewing my work and the constructive criticism is spot on – the writing is uninspired, full of repetition that makes for really boring reading. If I was looking for instruction with my work, I’d have my head on my keyboard having passed out after reading some of my stuff.

So how do I give my documentation some spark?

I’ve been using a thesaurus to find proper synonyms. I’ve also looking (really looking) at the text and asking myself:

  • “What are you trying to say here?”
  • “Does what you’ve written make any sense?”
  • “Is it in the active voice?”
  • “Can I tighten up the language to make it more accessible?”
  • How does it fit with other text in the section and the documentation as a whole

How do I create a sense of uniformity in the overall documentation but at the same time maintain some creativity in the writing so that it’s not all “Do this” or “In this screen you will see” type blather?

It comes down to focusing on the topic at hand while keeping the mind’s eye on the whole, just like life (platitude not intended).