How to write for a non-technical audience

"Two peoples divided by a common language." George Bernard Shaw said this about the British and the Americans, but the same can be said of anoraks and suits.

I have been on both sides of the fence: first, as a computer games programmer and then as CEO of a development company; finally as a journalist writing about technology for magazines like Director and Wired.

Now I sit right on the fence as writer-in-chief at Articulate Marketing, a company dedicated to helping technology companies get their message across to business people. This mission is also the subject of my blog, Bad Language.

IT people need to speak to the rest of the world. Emails, reports, budget requests, proposals, pitches, websites, manuals, FAQs, etc. etc. Get it right and your clients will love you. Get it wrong and you will mystify customers and end-users alike.

Since this is a site for IT contractors, let me try to approach the problem from an engineering perspective. What are the failure modes when technical people start writing?

• Too much 'how' and not enough 'why'. I regularly see reports written by IT people that spend pages on the technical details of a particular solution but cover the benefits to the buyer in a short paragraph. It's like a laptop review that tells you what the case is made of but doesn't tell you if the machine is good value for money.
   
• Too much detail. Completeness and accuracy are virtues that good software engineering instils. But sometimes 100 well-chosen words will make the point better than 2,000 words covering every detail. It's a question of prioritisation – you have no right to your readers' time.
   
• Jargon and acronyms. It's easy to scatter industry standard buzzwords and shorthand, assuming that every reader will know what they mean. Making assumptions about what readers know is dangerous.
   
• Wanting to sound big and clever. Research shows that using short words make writers seem more intelligent, but many people think they have to use long words and complicated sentences to appear smart. Too much IT copy looks like the winner of an obfuscated code competition translated into English.
   
• I want to take an engineering approach to solving the problems too.
   
• Top down design. The Pyramid Principle (Barbara Minto) brilliantly describes how to persuade people through writing. Writing to Deadline (Don Murray) talks about how to construct an article and tell a story. Both books are short and sweet.
   
• Get the syntax right. Check out the Economist Style Guide and The Elements of Style (Strunk and White) to learn how to write good, clean prose. These are like the Mythical Man Month – required reading.
   
• Requirements analysis. What is your document trying to achieve? Who is it for? What are the constraints? A good specification is the foundation of all good writing.
   
• Pick the right language for the job. Don't think you have to write like a PhD thesis in order to seem authoritative. If you write what you know as if you were explaining it to an intelligent friend over coffee, you won't go far wrong. Use everyday English words and short sentences.
   
• User testing. I recommend three kinds of testing: read the article aloud to yourself. Does it sound like you? Is it natural? Does it make sense? Ask a non-technical friend or colleague to read it and check that they picked up on the main points you wanted to convey. Finally, try to find someone who can proofread it properly - it's very hard to proofread your own work.
   
• Optimisation. Most prose can benefit from liposuction. Generally cutting the word count by 10 percent will improve any text. If you're writing for the web, aim for a 50 percent cut because people read slower online. Tools like Bullfighter and Microsoft word's grammar checker provide readability metrics to guide you.
   
• Best practice: Look at how newspapers and magazines convey information. They use short paragraphs, strong headlines, sidebars and boxed out quotations. They also write pithy opening sentences and strong final paragraphs. Do the same. And remember: paragraphs don't crash and a syntax error in a sentence is embarrassing but not a bug.

Matthew Stibbe