The Writing Process – Guide to effective writing for Technical Writers

October 18, 2008

Introduction

One of the more difficult tasks facing IT people is finding the best way of putting across technical information in a nontechnical way.

Nontechnical writing is often the most difficult type of communication for IT people (“techos” as they are sometimes known) to do well. This is because such writing calls for communication between people with widely different backgrounds.

Nontechnical writing takes technical information and translates into ideas that can be readily understood by people who are perhaps skilled in other areas or other disciplines.

Nontechnical writing presents a situation much like that involved with translating a foreign language. When you are speaking to someone who shares a common background and language, they can fill in the gaps and make up for mistakes in your communication. However when speaking to someone who has a different background and speaks a different language, they cannot make up for gaps and mistakes, and need additional explanation.

1. The Writing Process

This is a very important section for people who have not spent half their lives learning the many techniques of writing good, easy to read prose. While there’s no real substitute for those years, by applying some basic principles the result might be quite good.

1.1. Clear & effective communication

A subject as large as this could fill a library, but as big a subject as it is, there are some general guidelines which can be applied to help you write more readable reports.

If you are serious about becoming a better writer, you’ll take the following guidelines to heart and practice them. They were mainly put forward by the English writer George Orwell in his book Politics and the English Language (1947). Taught in university courses, practised by experienced writers everywhere, they can be considered some of the “tricks of the trade”.

By implementing the techniques outlined in this document you will be able to use language as an “instrument of expressing and not for concealing or preventing thought”.

1.2. No tired figures of speech

It is a fact that when communicating, people often use expressions and clichés that have become overworked. They may once have been full of impact, able to grab a readers attention with the freshness of their imagery. But after 1,000 uses, they are past their “use by” date and deserve to be retired. Take the time to think of new ways to express familiar ideas and your writing will benefit.

1.3. Short not long words

Never use a long word when a short one will do; use “timely” not “auspicious” or “opportune, use “set” rather than “predetermined”.

Short words tend to be more specific or concrete, making the message more definite. Short words also usually have more impact.

Use a specific, concrete word instead of a general, abstract one. Instead of: “We should request management to do something about their high overheads”, say “Let’s ask John, Susan and Peter to suggest five ways of cutting departmental costs”.

Examples of general (usually long) versus specific (mostly short) include:

stringed instrument/guitar.

transport vehicle/car.

public service department/Queens land Transport.

entertainment/movie.

science/biology.

sporting event/Olympic Games.

Specific words help by allowing the other person to see a clear meaning, general or abstract words tend to obscure meaning.

1.3.1. Economical & precise with words

Economical. if it’s possible to cut a word out without losing the meaning, always cut it out. For example to write: “You can begin to down load the data to the hard disk of the computer by loading the diskette into the diskette drive and selecting “down load” from the Utilities menu which is found in the System Administration area..” Is not as economical as: “To down load the data to the PC, insert the diskette and select “down load” from the Utilities Menu”.

They both get the same meaning across but the first includes extra words which add nothing to the clarity of the statement, but which the reader is obliged to plough through nevertheless. In this example it isn’t necessary to tell the reader where the down loaded data will go or where to insert the diskette or even that the Utilities menu is in the System Administration area if this section is dealing with the System Administration area as a whole.

The rule of thumb is, don’t make people read more than they need, they get in the way, waste time and cause irritation when done to excess.

Precise With around 500,000 words (not including technical), English has perhaps the largest number of words of any language. With such a variety, try to choose the words which best express your thought. Many words have only slight differences in meaning; i.e. assisted, benefited, served, helped. Or meritorious, illustrious, distinguished, significant, renowned.

The best way to achieve precision is to:

Think carefully about what you’re saying, and

Have a broad enough vocabulary. A good way to build your vocabulary is to make a point of looking up words you don’t know and perhaps using a thesaurus when writing a document.

1.3.2. Active not passive

Always use the active voice where possible. Active voice has more impact than passive voice and is usually more concise as well. For example it’s better to write: ‘use the active voice’ than to say: ‘the use of passive voice is to be discouraged’.

Notice the diluted effect that the passive voice creates. An enormous amount of what is written in organizations suffers from this problem. Why? Partly through habit, partly through a desire to lend authority to the words and partly to hide a lack of real understanding of the subject. Half-baked or incomplete thoughts tend to be expressed this way.

1.3.3. Everyday English not foreign, jargon or scientific

Except in situations where these are specifically called for, everyday English should be used rather than foreign, jargon or scientific words (i.e. not used for the sake of appearing knowledgeable). As a general guide, choose words that are likely to be understood by the largest number of people unless you are writing for a highly specialized readership.

It is often more difficult to use a common word when the concept is normally described in technical terms. Never assume that people know the meaning of technical words unless they have specific training (i.e. a computer science graduate can be expected to know computer jargon, but the accounts clerk who is actually using the software cannot be expected to understand computer jargon.

1.3.4. Prefabricated language

Orwell also pointed to the habit many people have of using “prefabricated” language. Rather than making the effort to think of new ways of describing things, most people lazily continue to use the same old expressions they’ve been using for years. For example: ‘At this point, the weekly invoice run is initiated and without further ado will run until finished.’ Contains two pieces of prefabricated language; “at this point” and “without further ado’.

The result of overused expressions is that the message may not get through since the reader has tuned out after encountering too many overworked phrases. Original sounding language helps get the message across by sparking the reader’s interest. In the above example, you could say: ‘The weekly invoice run now commences.” Not using prefabricated language also leads to the economical expression of ideas.

1.3.5. Present tense not past/future

Unless it specifically applies, use present tense. Say “Pressing accepts the default value” rather than “Pressing will accept . .” (future tense). Another example, “use active voice in the present tense” rather than “the use of passive voice in the future tense is to be discouraged’.

Using present tense makes the message sound more immediate. The reader unconsciously thinks if it’s happening now, it’s worth knowing. If it’s happening in the future, let’s wait until it happens. If it’s already happened, it’s history.

1.3.6. Avoiding overstatement

This general guideline applies to all communication. In an attempt to strengthen their message, many people resort to overstatement – words that convey an exaggerated view of a person, event or situation. If someone says “You never help me with my work” they invite a reply like “Of course I help you, what about last week?’.

When a speaker exaggerates it usually makes the other person defensive – all of which gets in the way of clear communication. It’s better to limit yourself to simply stating the facts, it shows that you’re being fair and mindful of the other person’s feelings.

1.3.7. Adapting words to the reader

To help the other person perceive what you’re saying as interesting and intelligible. Certainly, using precise specific words adds interest as mentioned earlier, but you can also add interest by being concise and colorful in your phrasing.

Another way to add interest is to use colorful, non cliché expressions. For example, to describe an experience as being “electrifying” is colorful but commonplace, to say it was “like touching an electric fence” adds color and freshness, making it both more interesting and entertaining for the listener/reader.

1.3.8. Never barbarous (advisory only)

Note: This section is for general interest only. It is included for the sake of completeness. Despite the fact that opportunities to use “barbarous” language in reports are limited, it is still worth mentioning since it is perhaps the most corrupting use of language seen today.

Orwell makes the point because he was appalled at the way governments would use terms like “collateral damage” to describe the deaths of innocent people, or their own soldiers being killed by “friendly fire” (mistakenly killed by their own side), or “ethnic cleansing” used to describe genocide.

Notice that barbarous terms are abstract, they don’t have a down-to-earth meaning. “Collateral damage” would become horrifying if the meaning was made concrete by showing the victims as real people – perhaps one’s own husband, wife or children. “Ethnic cleansing” sounds almost harmless but its real meaning is barbaric when you imagine it happening in your street, to people you know.

Why is it done? Usually as a way of legitimizing or “selling” acts of barbarism to people who would otherwise object. As an exercise, the next time a war occurs in which Australia or it’s allies are involved, listen to the way in which the events are described in the media. The words are carefully chosen to persuade us that the war is necessary because “we” are right and “they” are wrong. People often forget that there is no absolute right or wrong when it comes to why nations go to war. It is up to governments to “sell” the idea by glorifying our own cause and demonising the enemy’s.

1.4. Non sexist language

Care should be taken to avoid sexist (or nondiscriminatory as it is legally known) language.

As a general guide:

Make no gender assumptions – avoid using language which assumes a person’s gender. Today, there are very few jobs where a person is always male or female. Instead of saying “he/she” or “they” when mentioning a person, refer to their job title or function, i.e. “the data entry clerk” or “the user” or simply as “you”.

Don’t get carried away with removing apparent gender bias in language. With the best of intentions it can mutilate language. For example a “manhole” cover is the generic name of the object and to call it a “personhole” cover obscures it’s meaning and leaves itself open to ridicule, whereas “access” cover is acceptable.

Further information – if in doubt, consult the Anti-Discrimination Act and the Equal Opportunity in Public Employment Act relevant to your state.

1.5. Writer’s block

Common causes of writer’s block include:

Internal censor – imaginary, internal critic, speaking with the voice of teachers, parents or other authority figures. The censor makes us reject what might have been written before the writing process has a chance to get under way.

Fear of failure – originates also from authority figures. It makes us see writing as difficult or risky. It generates anxiety and lack of self-esteem (I’m a hopeless writer!)

Perfectionism - having unrealistically high standards, not setting realistic goals.

Procrastination - you begin by sitting down to make a start. After a time you’re thinking of all the things you could be doing – some of them quite important which should probably be done right away. Next thing you know, you’re doing that something else and thinking “Well I’ll get back to that later”. This is the gentle art of procrastination whose basis lies deep in the heart of human nature.

1.5.1. Preparation

The problem is often that you’re expecting to hear the finished product being dictated in your mind by that mysterious process called inspiration. But before the words will start to flow you need to know a lot about the subject. So if you are experiencing writer’s block, it’s generally a sign that you don’t yet know enough about the subject. Spend some more time preparing and getting to know the subject well.

1.5.2. Make a start

Another tip is to lower your expectations about the quality of output at the beginning and just write what you do know even if it sounds half baked. The important thing is to start the flow of words one way or another. Concentrate on getting as much down as possible with the intention of going back and correcting it later. It doesn’t matter at this stage how bad it sounds, no one else need see it. Anything you write now can be changed later in the light of a better understanding of the subject.

1.5.3. Review the reference material

If that doesn’t help, go back and review the reference material you have prepared. A lack of reference material as discussed in the previous chapter is the source of writer’s block. It highlights the importance of thorough presentation to the success of the documentation.

1.6. Environment

Most people work best in a quiet, comfortable environment, as free as possible from interruptions and distractions. Easier said than done in many work places, particularly when the telephone never stops ringing and coworkers frequently want to chat.

It is important to arrange a time and a place during the working day where you can work in a quiet, interruption free environment, since you need to be able to concentrate and follow a train of thought for an extended period.

1.7. Routine

Get into the habit of writing everyday. It helps to reinforce the writing process and to overcome writer’s block.

The process of writing involves using the part of your mind that performs the enormously complex task of turning ideas into language. Unless you use this acquired skill regularly, it falls into disuse. It gets rusty and won’t work properly. It’s similar in some ways to physical fitness. Just as regular exercise keeps a person fit, writing something every day helps to keep your writing faculties in good working condition. Schedule a period each day to work on the documentation and do everything you can to stick to the schedule. If your other commitments make it difficult to allocate time on a regular basis, discuss the matter with your manager with a view to reorganizing your work load.

1.8. Ergonomics

Since writing involves sitting in one position for long periods, certain ergonomic factors need to be considered. These include the following:

1.8.1. Chair

Provide yourself with a chair that gives good lumbar (lower back) support. Try to avoid slouching in the chair for long periods as this places strain on the lumber vertebrae.

1.8.2. Screen

The screen should be on or around eye level and not closer than around 40 centimeters. Screens (liquid crystal flat screen types excepted) do emit a small amount of radiation. While no definite proof exists that this radiation is harmful to humans, many people do report degrees of discomfort and eyestrain. Common sense would suggest trying to minimize your exposure. Using an earthed radiation shield is recommended. The intensity of radiation coming from a screen decreases rapidly the further away the screen is. Therefore, position the screen to be as close as it needs to be to allow your eyes to comfortably read the words on the screen, and no closer.

Adjust the brightness to be just bright enough rather than brighter than necessary. If the brightness needs to be high to overcome reflected light from windows, either rearrange the screen away from the direct light, or arrange blinds. All of this helps to minimize eyestrain.

1.8.3. Regular breaks

Occupational health guidelines recommend taking a break every hour by getting up and walking around. This not only helps your circulation and eyes, it also clears the mind.

1.8.4. Keyboard

Your wrists should not need to be bent while using the keyboard. Studies show that Repetitive Strain Injury (RSI) can occur where a keyboard operator, over a long period, constantly types with bent wrists. The strain is due to the tendons which pass through the wrist from the lower arm to the hands becoming inflamed because they are being stretched and constricted as they pass through the narrow aperture in the wrist known as the Carpal Tunnel.

Avoid this possibility by making sure the keyboard is not too high. Either adjust the seat higher up, or arrange for a lower desk or a keyboard drawer which fits under the desk top, or a wrist support pad.

Posted by white smoke | Filed Under Accurate Spell Checker, Correct Grammar Software, Error Explanations, Grammar Correction, Grammar Software, Intelligent Style Checker, Writing Software, editing, editing proofreading, english learning, english writing, esl software, grammar checker, proofreading, proofreading software, punctuation, verb tenses, white smoke, white smoke review, whitesmoke, whitesmoke review, writing, writing proofreading

Related Posts:
White Smoke English Writing Software Benefits
English Lessons With White Smoke Grammar Correction & Writing Software
Scientific and Medical Writing
White Smoke Writing Enhancement Software Review
White Smoke Grammar Correction & Writing Software Review

Main Navigation