Whether we realise it or not, technical documents are part of our everyday lives, both personal and business. When you buy a dishwasher, it comes with instructions on everything from how to turn the thing on, to how to unblock a pipe! Technical documents are written for all of us, not just computer geeks assembling a rocket to travel to Mars. But in this blog, let us focus on the importance of technical writing in the IT world and what we can do to help clients get the most from the products they offer.
Understanding your audience
Having an in-depth understanding of your audience (those reading our documentation) is key to writing effective technical content and the most important step for anyone who endeavours to write a technical document. We must understand who the audience is, and the level of detail they need. We must never presume that they know something, they may not.
This is a ‘technical’ document. It’s not a Patricia Conwell novel where you sit by the fire at night with your feet up, intrigued by who committed the heinous crime. This document is for reference and our audience are already frustrated because they are only reading the content because there’s a problem. Finding what they want quickly is key.
If we don’t understand our audience – the knowledge they already possess, what jobs they perform, our document will be thrown out of the window pretty quickly. So, interviewing our intended users would be a good start. Getting feedback on the previous online help we created would also be a step forward in getting into the minds of our readers.
Clear, Concise and Consistent
“Imagine every word costs you ten pounds!” That was my first lesson as a technical author, and I’ll never forget it. Made me think about every word I use…why use three words when one will do? So be concise. These days, when a reader sees masses of text facing them, it can quickly scare them off, especially if they are already frustrated.
Forget those beautiful adjectives/adverbs that we like to use (and perhaps we are really good). So the instruction, “Please click the Test button to quickly check the connectivity of the database” should become “Click the Test button to check the connectivity of the database”. See, I saved twenty pounds!
When a famous chef says, “Throw in a cup full of sugar” when teaching an international audience how to make that Lemon Meringue pie…. heck, what does that mean? How much sugar is that? Stating clearly and exactly what is needed is vital, and so avoiding terms that may not mean the same thing to someone from the United Kingdom as opposed to the United States.
Then there is consistency. I remember going to a company once where all the developers were writing the help files and user guides. One developer wrote in a procedural style i.e. step 1 do this, step 2 go here etc, another developer wrote instructions in the body of a paragraph. It confused the readers, making it hard to follow and so they tuned out. Having a consistent style makes it a pleasure for customers to search through and find what they are looking for quickly. It is vital to have a Style Guide – where generally one individual (the Technical Author) creates a document that lists the fonts that must be used, the size of logos, how the company uses abbreviations etc. This ensures a consistent standard throughout the whole company.
Poor grammar…poor product?
If there were grammar mistakes all over the place, could it be said that this may reflect poorly on the software the company are offering? Typos and poor sentence structure may never get checked (yes, I know your checking my grammar now). Could the client be thinking that the product doesn’t get tested very well either? Pronouns (he/she/them/they) for example could confuse our reader if not used properly. I’ll give you a brief example and then we’ll bring this to an end. Look at this sentence:
Luke interviewed Ben when he was available.
It’s unclear whether it’s Luke or Ben that was available. A technical author would change this to:
When Luke was available, he interviewed Ben.
Until next time for part two