Most of us find it difficult to write clearly and concisely, especially with a technical document such as a user manual or a requirements specification. Here are a few do's and don'ts.... VERBOSITY

Many people have the idea that writing has to appear 'technical' and academic-looking. They sprinkle long words into long sentences, thinking that this is good writing. Many professionals, including lawyers, teachers and university dons do this, and as a result write poorly.

Consider this statement that appeared in the Australian press in March 2001:

'The Lotus management team has made the determination that evolving market needs, and continuing to effectively meet customer demand require us to restructure. We are evaluating all resources and processes that are market-facing and customer-facing to enhance and improve those areas and drive performance levels higher.'

Not particularly clear, is it? Much more of this and the reader will quickly switch off, become frustrated and may form an idea about the competence of the writer - and their organisation! Much of the above is verbal treacle. We should aim at brevity.

Consider: 'The Lotus management team has decided to re-structure to meet changing business demands.'

The following example appeared in The Age newspaper, April 18 2002:

'The company continues to commute cedant relationships. One commutation has settled legal disputes with a major cedant resulting in a substantial reduction of the company's liabilities. Due to the inherent uncertainties remaining in the companies' business directors consider that the prudent course is to use commutation gains in excess of known adverse developments to establish a prudential margin.' Company Secretary, Reinsurance Australia Corporation

How many people would understand this pompous gobbledygook?

It has an average of 24 words per sentence, and has 25% long words (three or more syllables). We can measure the clarity of the writing if we wish, and this can be measured. Two examples of commonly-used measures using these criteria (words per sentence and percentage of long words):

Gunning index = (24 + 25) * 0.4 = 19.6
Flesch reading index = 20.3%

Your word processing package can produce these statistics for you. Most bad writing can be improved by shortening the sentences and by using simpler words. Sometimes the writing has to be re-structured. If your writing demands the use of long words or technical expressions then use short sentences to compensate.

SOME HINTS FOR BETTER WRITING

* Why use one word when you could use many?! Condense expressions like these:

run at around... try average
be in a position to... try be able to (or omit entirely)
at this point in time... try now

* Don't babble!

These examples were found in government documents:

Offices open in the morning, not antemeridian hours.
Documents in envelopes, not folding containers.
Payments recorded in receipts, not consignment notes.
Requests may be refused, not subjected to an absence of approval.

* Redundancy

We often use unnecessary words, like advance planning. The words in italics are redundant:

ask a question
close proximity
combine together
broad overview
brief summary
for a period of three weeks
totally destroyed

* Contradictions

It is not uncommon to see phrases like 'a detailed overview' and 'broad details'.

* Use the correct word!

There are many like-sounding words. Here are some errors seen recently:

who's instead of whose
they're instead of their
it's instead of its
its instead of it's
sort instead of sought

* Have a recognisable structure

* Have a beginning, middle and end
* Define what is to be done, then how - the detailed calculation etc
* Use a standard format
* Use paragraph headings
* Use paragraph numbering and relate these to your process models
* Identify input files, output files
* Distinguish between read-only, write, create, and delete processes

* Use a good style

* Error messages - if you're down to this level of detail, try standard messages with parameters
* Write from the point of view of the system, not the user
* Identify keywords - Use a glossary and a data dictionary
* Use the present tense, not the future
* Use imperative, command statements


Orwell's (George, of 1984 fame) six rules for plain prose:

1. Never use a metaphor, simile or other figure of speech that you are used to seeing in print.

2. Never use a long word where a short one will do.

3. If it is possible to cut a word out, always cut it out.

4. Never use the passive sense where you can use the active.

5. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.

6. Break any of these rules sooner than say anything outright barbarous.

SUMMARY

Good writers (the ones who write best-sellers) know and understand these rules - and we buy their books. Although we're not writing novels, we have a particular objective in mind. We should try to write our specifications using these rules, to make them readable, understandable, concise and unambiguous.