A good IT all-rounder can usually write clearly in a logical sequence, and can do it in such a way as to prevent the reader going into a system shutdown. It is as important a skill in any team as being able to place a sticky note on a whiteboard, or write an application installer.

While writing isn't a much-celebrated skill in IT, it is a valuable one that comes into play in a variety of teamwork. Systems that are clearly and reasonably documented are easier to maintain. The better you can explain a technology, the more likely others will adopt it, or appreciate the effort you took to master it.

I spend a lot of time these days reading IT documentation and articles and have noticed the recurring faults that always seem trip up the writer, and then subsequently confuse and frustrate the reader

Getting the sequence muddled up. Your train of thought must be reasonably obvious, without leaving steps out. Your statements must be in the right order.

Lapsing into jargon. When you are working closely in a team, everyone tends to lapse into a shared private language that is intelligible to team members but baffling to outsiders. In larger groups we gravitate towards Three-letter Acronyms (TLAs) that, if you use them to devoted relatives, or friends in the pub, will result in you talking to yourself. You must never assume that readers will be familiar with your private language. Managers are unlikely to be

It's all about 'me' or ('we'). Alas, if you have read too many literary narratives about one person's struggle towards spiritual growth, or trans-continental road-trips, you will involve yourself in the narrative; "I/we struggled with the interface, and spent many sleepless nights understanding the technology." No. In moderation, perhaps, but you must stand back and just write about the technology, rather than your personal interaction with it.

Using formal 'textbook' language. Written language is a compromise with spoken language, but when writing technically, many writers lapse into an oddly formal brand of textbook language, where everything is expressed in the passive tense. Cats don't sit on mats, but rather mats often contain a sedentary cat. The English language offers several ways of expressing a thought. We can use the clear subject-verb-object sentence of middle English when speaking to others, choose instead the flowery Norman-French if we need to sound dignified and we even sometimes adopt the Latin if we need to give the impression of spiritual intelligence. It is best to write simply, in plain English, but in a conversational way that sounds natural if read aloud.

Using Industry clichés. Clichés often seem to be the correct way of saying things, simply because they are used so frequently. To this, we add the industrial patois, based on military slang, with excruciating phrases such as 'heads-up', 'ameliorating concerns', 'the learning curve', 'pushing the envelope', 'rocket science', 'going forward', 'zero-sum game', 'the chicken-and-egg situation', and 'win-win situation'. Again, stick to plain English.

ThingammyJigs. In IT we often run short of a suitable vocabulary because the technology is so new. Coopers, for example, aren't lost for words for describing how casks and barrels are made. All such long-established technologies have a technical word for everything. We use words like 'environment', 'situation' or 'scenario' when we are lost for words. Some good IT glossaries are maintained, including one for SQL Server, and it is best to use the right terms where possible.

Phil Factor.