Perhaps the single most important aspect of technical writing is clarity - making your meaning readily apparent and unambiguous. If your document is unclear, then not only are you wasting people's time as they try to read and understand it, you could cause potential disaster if they misapprehend a crucial safety guideline, or misuse software with sensitive data. Your entire document must be as efficient and effective at communicating the information as possible. Seven rules for clarity:

1. Be consistent

I've been harping on that one for a while, but it's key. Use only one term for a concept, only one concept for a term. Always explain things in the same format - don't try to 'spice it up' by changing the familiar format. Indicate important points or special nomenclature the same way each time. Create your style guide and thesaurus and use them.

2. Be concise

Long-winded sentences are much harder to understand, and they waste a reader's time. A sentence that rambles on, occasionally stopping for tangential knowledge, or worst of all holding the most pertinent information until the end of the sentence - like this one is doing, in case you hadn't noticed - is the most difficult to read and understand. (see?) It forces us to hold all that information in our head before we can make any connections. Sometimes we can't - we lose the thread of the sentence and have to start over. Often we'll only understand on a superficial level, as we've had to expend too much concentration on that single sentence, and have lost the flow of concepts from the sentences around it. Get to your point, and then get out.

3. One concept to a sentence and paragraph

It's something that we all learned in primary school, and yet so many people forget it. A sentence should concern one concept - a single, discrete idea. A paragraph should contain sentences that relate to the same concept - there shouldn't be a sentence that doesn't directly relate.

4. If in doubt, keep it simple

Complex sentences with multiple phrases take longer to understand. They're also easier to misuse - the more phrases and clauses you add, the more likely you are to accidentally violate the more subtle grammatical laws, and wind up with a sentence that's hard to understand. Short, simple sentences are easiest to understand - and to translate.

5. Target your language to your audience

Words from Roget's are rarely your friend for common user documents. Stick to plain language - you're not writing a novel. For more specialised products like financial software or an advanced engineering specification, jargon (that is, words not commonly understood that have a special meaning within a field) is essential for communicating a concept concisely - your target audience will be familiar with that language. Always keep the end-user of the document in mind.

6. Use logical ordering

Recipes list the ingredients and tools required before the recipe starts - technical documents should do the same. Safety information belongs where the reader will discover it before they perform the unsafe action. Conditional actions should be written with the 'if' first - ie, not "Press the red button and hold for three seconds if the alarm sounds" - half your readers will have already pressed the button before they got to the "if" part. If they didn't need to do that action, you've confused them - it sounded like they had to do something, and then it turned out to be optional halfway through. Phrasing it as "If the alarm sounds,  hold the red button down for three seconds" means your reader knows they have to evaluate the situation first. Write your document in the order that people think or encounter the situation.

7. Use diagrams only where it will improve understanding

A pictures is only worth a thousand words if it's a necessary picture. Don't add diagrams just to break the text up, or because all your other topics had a diagram. Processes that have diagrams send a signal that they're complicated, and if what you're documenting isn't that involved then including a diagram may have your reader looking for complexities that aren't there, or spending needless time understanding your diagram. If it's not essential to communicating the concept, it doesn't belong in the document.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2