A Guide to Writing for Computing Students

• Introduction
• Writing style - in general
• Orwell's Rules on Writing
• Writing Style
• A Word on Revision
• Technical Writing
• A Technical Report
• British Standard format
• Hints on Academic and Technical Report Writing
• Suggestions to Help You Improve Your Writing
• Some Faults In Writing
• Rules for Efficient Communication
• Reference Section
• Punctuation
• Misused and Confused Words
• Bibliography

• Notes on Reports and Documentation from Tony Drewry
• Some Notes on Writing a Project Report from Barbara Segal.

During this course you will write and present for assessment many different types of document. These will include academic reports, technical reports, program specifications and technical instructions for other people to follow and understand. This pamphlet has been produced to help you in the task of writing. This is not a definitive document, further reading and reference texts are listed in the bibliography. The quotation below says, quite succinctly, what the aim of a writer is. I recommend that you read the book from which the quotation is taken.

"I have tried to keep my language as simple as possible. Not only because Zen teaches and advocates the greatest economy of expression, but because I have found that what I cannot say quite simply and without recourse to mystic jargon has not become sufficiently clear and concrete even to myself."
(Eugen Herrigel, Zen in the Art of Archery.)

You will find that throughout your life you will be judged by your writing; that your value as a student, and later as an employee, depends not only upon your knowledge of software engineering but also on your ability to communicate information and ideas.

"The popular picture of the engineer, for instance is that of a person who works with a slide rule, T-square, and compass. And engineering students reflect this picture in their attitude toward the written word as something irrelevant to their jobs. But the effectiveness of the engineer - and with it their usefulness - depends as much on their ability to make other people understand their work as it does on the quality of the work."
(How to be an Employee, Peter F. Drucker (1952)).

Think what your writing is about. Two processes are involved in written communication.

• The first, in your mind, is the selection of words to express your thoughts.
• The second, in the mind of the reader, is the conversion of the written words into thoughts.
• The essential difficulty is in trying to ensure that the thoughts created in the mind of the reader are the same thoughts that were in your mind.

Here are George Orwell's six rules on writing. This is probably the best short advice on the subject. Orwell, one of the great essay writers in English, followed his own advice.

As he explained, "One can often be in doubt about the effect of a word or phrase, and ne needs rules that one can rely on when instinct fails. I think the following rules will cover most cases:

1. Never use a metaphor, simile or other figure of speech which 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 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.

A metaphor

is the deliberate use of figurative language, expressing an abstract idea in concrete terms. It sets a picture before the reader, and is therefore often a more forceful way of making a point. e.g. "He is a lion in battle. "

A simile

is a formal comparison, expressing the resemblance of one thing to another of a different category. eg. "good as gold", "as cool as a cucumber", "the sea was like a millpond".

If either a metaphor or simile is over used, it will become a cliche. In technical and academic writing it is good advice to avoid using both similes and metaphors. Following this advice will also mean that you avoid the use of cliche.

The passive voice

eg: "It has been decided that there will be more taxes.", avoids responsibility and is vague. Who decided? (also eg: "The letter was received by the manager.")

The active voice

tells who did what (eg: "The Prime Minister decided that indirect taxation should rise."; "The manager received the letter.")

Passive voice almost always ends up with a sentence structure that is lengthy and lacks the vigour and forcefulness of the active voice.

Jargon

is usually ugly-sounding and difficult to understand, in fact it is the opposite of plain English. It involves the careless misuse or overuse of technical or semi-technical terms.

"Manpower ceilings are a very blunt macro-instrument and will be either ineffective or unduly restrictive if not based on the results of management reviews and other 'micro' activities... ceilings are biting, but this is what they were meant to do."

It is not possible to interpret exactly what the writer means but the sentence could probably read:

"An overall restriction on manpower should only be applied when all details of the situation have been fully considered. Restrictions will bring difficulties but this is what they were meant to do."

One should of course remember one's audience. When a report or paper is written for an audience of scientists, engineers, academics or for a profession; that has its own jargon or phrases. Then use of that jargon and particularly scientific and technical language would be more readily acceptable.

One should consider that a report will communicate your message better, if it is understood by a larger audience, you should be aware that, in industry your reports will be read by non-technical people, for example managers and accountants. It is of course those people that have the decision as to whether you get funding for your next project, or funding to continue with your present project.

barbarous

By "barbarous" Orwell meant "destructive", in the sense of confusing the language and its meaning, and being intentionally misleading.

Writing Style

1. Consider the title and the terms of reference.
2. Define the purpose and scope of the composition.
3. Consider the time available and allocate this time to thinking, planning, writing, and revising.
4. Make notes of relevant information and ideas.
5. Decide what the reader needs to know.
6. If possible, identify your readers and prepare a circulation list.

1. Prepare a topic outline.
2. Underline the points which require most emphasis.
3. Decide upon an effective beginning.
4. Number the topics in a logical order.
5. Decide upon an effective ending.
6. For a report, decide what illustrations and photographs you will need.

1. Write your draft on wide-lined A4 paper.
2. Type your draft using a word-processor.
3. Allow plenty of time, free from interruptions.
4. Use the topic outline as your guide.
5. Use effective headings and keep to the point.
6. Start writing and keep going until you have finished your first draft, using the first words that come to mind. It is the flow of ideas that are important at this stage, the English can be polished up later.

1. Does the composition read well?
2. Are the important points sufficiently emphasized?
3. Is anything essential missing?
4. Are there faults of logic or mistakes in spelling?
5. Is the meaning of each sentence clear and correct?
6. It is important to review long sentences.
7. Does the writing match the needs of your readers, in style, abbreviations, symbols, mathematics, illustrations and any technical jargon you may have used.
8. Put your composition on one side for a while and then revise it again.

A Word on Revision

• Care must also be taken in revising written work not to lose the natural flow of the words.
• Language that is artificial in its bluntness and simplicity may lack interest and style. How many revisions you make to your work and at what point you stop revising your work, will, like many skills only come with practice.
• The more you practice the better and more proficient a writer you will become.

Talking about the writing of his novel Saturday Night and Sunday Morning; Alan Sillitoe said,

'It had been turned down by several publishers but I had written it eight times, polished it, and could only spoil it by touching it again'.

Further Hints on Writing

1. devising a writing plan of what you are going to say;
2. thinking about and arranging the order in which you are going to introduce your information;
3. proof reading your text.
   • Be self critical.
   • A good method is to read it aloud to yourself, or get a colleague to read it and offer constructive criticism.
   • Beware Husbands, Wives, and Mothers are notoriously, unbiased critics!

• Edit and rewrite; do not be afraid to cut out or rephrase unwieldy sections.
• Read good technical journals, e.g., New Scientist.
• Read the quality newspapers.
• Read good literature, although you should take care. Good writers do not always stick to the rules. Emily Bronte, for example, has the writing skill to hold together a 64-word sentence and still maintain a clarity of expression and flow of ideas. Until you are more experienced at writing; you will probably make fewer grammatical errors and write sentences that do not confuse the reader if you maintain a sentence length of no more than 25 words.
• Above all read carefully and precisely. Do not emulate Woody Allen, "I took a course in speed reading, learning to read straight down the middle of the page, and was able to read War and Peace in twenty minutes. It's about Russia."
• During your reading you will discover words that are new to you. There may be a few in this document. Check, using a dictionary, the meaning of any new word you find; take note of how the writer has used the word, and the context in which the word has been used. You will find that gradually your vocabulary will increase, and you will be using words in their correct context. If you find it helpful keep a list of words that may be useful to you. Do not write down just their dictionary meaning, but also use the word in a sentence.
• Practise. Writing is just like playing a musical instrument, or participating in a sport, the more you practise the more proficient you become.
  Back to Top

  ---

  Technical Writing

  • How to Write Instructions
  • A Technical Report
  • A Research and Development Report (BS 4811 and ANSI Z39.18)
  • Hints on Academic and Technical Report Writing

  ---

  How to Write Instructions

  The purpose of instructions is to tell a person who is not familiar with a task how to do that task.
  A common example is the many car maintenance manuals that enable DIY mechanics to maintain their cars.
  The instructions must be
  • complete so that they explain the action required and answer all relevant questions.
  The instructions must be
  • clear,
  • concise,
  • simple, and
  • easy to understand.
  They must therefore be written by someone who has experience of the task.
  1. Consider who the instructions are for.
  2. Precede the instructions by any explanation (especially the reasons for changing an
  3. established procedure).
  4. List all materials required.
  5. State any safety precautions; and if necessary repeat these immediately before the step in which the precautions are to be taken.
  6. Arrange the instructions in the order in which things are to be done.
  7. Indicate the action required at each step by a separate statement.
  8. Use complete sentences written in the imperative (as in this list).
  9. Number the successive steps, so that the action required at each step stands out.
  10. If drawings, photographs or samples are used, place each one next to the words it illustrates.
  11. Work through the instructions.
  12. Arrange for a trial by at least two other people, one with experience of the task and one without.
  13. Revise your draft, if necessary, after the trial. Add your initials and date.

  ---

  A Technical Report

  A technical report is not written in the same style as an English essay, although both demand a good standard of writing. The task in writing a report is to communicate the results of your research or experiment to an audience of both technical and non-technical persons.
  The layout of a report is in the form of section headings, below is the report format you will be expected to adhere to during this course.
  1. Report Title
  2. Name and Date
  3. Objective of Experiment or Title of Experiment
  4. List of Apparatus. This must include the serial numbers of any instruments which are used. The purpose of this is so that, if you have any erroneous results, it is possible to check the instruments to see if they are at fault.
  5. Layout of Apparatus and/or Circuit Diagram. The drawings should be of good size and adequately labelled. Where several instruments of the same type are used, they must be identified by their serial numbers. Standard symbols should be used on circuit diagrams.
  6. Method. You must describe how the experiment was carried out and the description must be in the past tense and impersonal. eg. 'The apparatus was connected as shown in the circuit diagram (Fig. 1). The power supplies to the apparatus were switched on, and the meters checked .....'
  7. Theory. Where a particular theory is applicable it should be stated. If the experiment leads to the development of a further theory by you, include it in this section.
  8. Results and Calculations. The results must be tabulated. Where many similar calculations are required it is only necessary to show the complete working out of one or two. Graphs, where applicable, should be included in this section.
  9. Conclusions. The first thing to consider is whether the objective has been achieved. Where a standard result is available (eg. density, resistivity, etc.) it should be compared with your result. Any errors must be pointed out and an attempt made to explain why the error occurred. Criticism is valid only if it is objective.
  10. References. List any books or technical pamphlets you have used, along with the author's name, date of publication and the name of the publisher. This enables any person who wants to repeat your work, or extend it, to go back to your sources.

  After you qualify and get a job in industry, you will find that the company you work for will have its own required format for a report. This will probably be based on the British Standard BS 4811 or, if the company mainly works for American companies, the American Standard ANSI Z39.18.

  The following report format is a British Standards format, used by many British Companies.

  A Research and Development Report (BS 4811 and ANSI Z39.18)

  • Front cover }
  • Title page } or Report documentation page (ANSI)
  • Summary (abstract) }
  • Table of Contents
  • Introduction
  • Theory
  • Experimental procedure (listing apparatus, with serial numbers) Results
  • Discussion
  • Conclusions (must be precise, orderly, clear and concise)*
  • Recommendations (arising directly from the conclusions)*
  • Acknowledgements
  • List of References
  • Appendices
    • Tables
    • Illustrations (if not included in the main body of the text)
    • Graphs (if not included in the main body of the text)
    • Literature survey (if necessary)
    • Bibliography (supplementary to references cited in text)
    • Glossary (if necessary)
    • List of abbreviations, signs and symbols
  • Index (if necessary)
  • Distribution list
  • Back cover
  * Alternatively, the conclusions and recommendations may be placed immediately after the introduction.
  Back to Top

  ---

  Suggestions to Help You Improve Your Writing

  • Some Faults In Writing
  • Misused and Confused Words

  ---

  Hints on Academic and Technical Report Writing

  1. Qualify statements. If you make a statement, state where the proof of that statement can be found. eg., "Did you know that the software lifecycle actually follows the Buddhist or Hindu model of the human lifecycle, and not the Judo-Christian one?" [Zen & The Art Of Reverse Engineering, Corporate Computing, Jan 1989].(see below)
  2. Quote references, that is if you are quoting another person's work, or you are quoting facts you have found in a book or magazine, state where you got the facts from, who wrote them, etc. eg.' "The Macintosh IIx uses the Motorola 68030 micro-processor, the micro-processor has a clock rate of 16 Mhz." [Apple Business, Nov 88]. (see below)
  3. Use the third person in all report writing.
  4. If you are using a word too often, use a thesaurus to find an alternative word with the same meaning. Care should be taken, when doing this, not to obscure a word. Remember Orwell's rule above, and the fact that using long, obscure and complicated words does not always indicate that the writer has a profound statement to make. In most cases it just indicates that the writer is trying to hide the fact that he does not fully comprehend the subject he is writing about.
  5. If you are using a new or unfamiliar word, always check that the word means what you think it means. This could also apply to words you use 'loosely' in your everyday spoken English. Remember the function of technical and academic writing is the accurate and succinct communication of your observations.
  6. Use a word processor with a spelling checker! This also makes it easier to revise.
  • Tips 1 & 2 above will enable you, or some other person to check back on your references at a later date; either to validate your research or to expand on your original work.
  
  Back to Top

  ---

  Some Faults In Writing

  • Unscientific Writing
  • Tautology
  • Circumlocution
  • Reasons for Verbosity
  • Misused and Confused Words
  • Rules for Efficient Communication

  Unscientific Writing

  Example 1

  "The complaint of examiners that students cannot write good English applies, I think, mainly to engineering students. As their abilities lie outside literature, it is not surprising that engineering students write badly."
  Some faults in the above:
  1. An opinion is expressed and later stated as a fact.
  2. The author gives no evidence in support of the implication that students are good at either literature or engineering.

  Example 2

  "Under present day conditions there can be little doubt that nitrogen is perhaps the most important factor in feeding the world. It is not necessary to stress the fact that..."
  Some faults in the above:
  1. There is excessive qualification in the first sentence.
  2. In the second sentence the writer is about to stress something which does not need to be stressed.
  3. If something is stated as a fact it is not necessary to call it a fact.

  Example 3

  "The last ten years have seen changes in teaching of a magnitude unequaled in any previous period of our educational history. Such advances have necessitated a monumental expenditure of money and human resources, and it is interesting to note that whereas in countries like the United States..."
  Some faults in the above:
  1. "Years have seen" is teleological. Years cannot see.
  2. "Of a magnitude unequaled" means unequaled.
  3. "In any previous period of our educational history" is ; it tautologicalshould read "in our educational history."
  4. Changes are later referred to as advances.
  5. Advances do not necessitate.
  6. Expenditure cannot be monumental.
  7. The words "it is interesting to note that" can be omitted without altering the meaning
  8. of the sentence.
  9. The first sentence refers to education in Britain between 1964 and 1974. Is this statement true?

  ---

  Tautology

  Tautology - Saying the same thing twice using different words.
  Examples
  • Every individual one;
  • may possibly go;
  • the reason for this is;
  • one after another in succession;
  • as an extra added bonus;
  • in my own personal opinion;
  • in equal halves;
  • symptoms indicative of;
  • temporary loan;
  • but ... however;
  • enclosed with this letter.

  ---

  Circumlocution

  Circumlocution - the use of many words where few would do better.

  Circumlocution	Better English
  if at all possible	if possible
  on an experimental basis	by experiment
  an oral presentation	a talk
  on a theoretical level	in theory
  We are in the process of making	we are making
  Experiments are in progress to assess the possibility of using	We are trying to use
  It was observed in the course of the experiment that ...	We observed ...
  In view of the fact that	because

  ---

  Reasons for Verbosity

  Tautology, circumlocution, ambiguity and verbosity arise from ignorance of the exact meaning of words. Also, people may use too many words (or too few) if they have not considered the difference between speech and writing.

  Sometimes in conversation we use more words than are needed in writing. We use words to separate ideas; we repeat things for emphasis; and we correct ourselves in an attempt to achieve greater precision. These things give the listener time to think.

  On the other hand, in conversation, we take short cuts, leaving out words, and so use fewer words than would be needed to convey the intended meaning. Also in conversation, we use body language and eye contact to re-inforce the meaning of the words we are using.

  Remember that at times a graph, illustration or photograph may explain your meaning much better than any number of words. For example you would never attempt to describe a circuit diagram in words. How would you best describe the process of wiring up a mains electrical plug? and if given the task of wiring a plug up which type of instructions would you prefer to follow?
  

  Back to Top

  ---

  Rules for Efficient Communication

  1. Always decide what you wish to say, why you wish to say it, and whom you hope to interest, before you start to write.
  2. Plan your work so that information and ideas can be presented in a logical and effective order, and so that the whole composition has the qualities of balance and unity.
  3. Write for easy reading.
  4. Revise your work.

  Write for easy reading

  • Begin well.
  • Keep to the point.
  • Be clear, direct and forceful.
  • Maintain the momentum of your writing to the end.
  • End effectively.
  
  Back to Top

  ---

  Reference Section

  colon | comma | semicolon | hyphen | dash
  Misused and Confused Words

  ---

  full stop

  The full stop is used to mark the end of all sentences except direct questions (?) or exclamations (!). A capital letter is used to mark the beginning of all sentences. In writing the single most important rule is that a sentence is a complete thought. (Or, a sentence has a subject and a verb.) "Joe thinks" is a complete thought - it names someone or something and tells what he or it did. Similarly, "The dog chased me down the street" is mainly about the dog and what it did. Anyone can understand the sentence, whether he or she read what went before or after it. It makes sense by itself. "The dog chased" does not make sense, nor does "Me down the street". When writing, learn where to pause. Read your writing back to yourself to find out where to pause and where to stop.

  ---

  colon

  A colon is correctly used in a sentence when the statement that follows the colon explains, balances, or completes in some way the statement that precedes it, as in 'This is an excellent play: the characters are believable, and the ending unexpected.' A colon is also used to mark the beginning of a list of items as in 'The following apparatus was required: a volt meter, a power supply and an oscilloscope.' Do not use a colon when items of a list come immediately after a verb or preposition:
  Wrong:
  The job requirements are: typing, shorthand, and bookkeeping.
  Right:
  The job requirements are typing, shorthand, and bookkeeping.
  

  ---

  comma

  In general, a comma marks a pause or slight break in a sentence; it is a less complete separation than one indicated by a semicolon, a full stop, or brackets. The rules governing the use of a comma are many and varied, and you are recommended to read one of the reference texts listed in the bibliography.

  ---

  semicolon

  Study this quotation carefully:
  "Do not be afraid of the semicolon; it can be most useful. It marks a longer pause, a more definite break in the sense, than the comma; at the same time it says 'Here is a clause or sentence too closely related to what has gone before to cut off by a full stop'. The semicolon is a stronger version of the comma."
  [The Complete Plain Words, p. 261.]
  
  This quotation is worth noting; it summarizes well what you need to know about the semicolon.

  ---

  hyphen

  The prime function of the hyphen is to prevent ambiguity. Its main function is to link the parts of compound words:
  • bench-mark
  • cross-section
  • frying-pan
  • wing-span
  The hyphen is used to form compound adjectives:
  • high-rise flats
  • a water-cooled engine

  ---

  dash

  You can write good, well-punctuated English without using dashes at all, but they do have accepted use. A dash can be used for emphasis, to indicate an abrupt change, or with explanatory phrases or words (in place of commas or parentheses).

  In pairs to mark a parenthesis:

  A combination of three types of study - two on humans and one on animals - indicates strongly that alcohol is harmful to unborn babies.
  • Note: Be sure to use dashes both before and after a phrase when it is in the middle of a sentence, not a dash before the phrase and a comma after it.

  To introduce an explanation:

  It takes two to speak the truth - one to speak, and another to hear. [Thoreau]

  ---

  Misused and Confused Words

  a, an | accept, except | affect, effect | all ready, already | conscience, conscious
  fewer, less | maybe, may be | to, too

  ---

  a, an

  • The form a is used before words beginning with a consonant, as in a road, a hospital, a computer.
    • It is also used before words beginning with a vowel which is pronounced with a consonant sound, as in a one-way street, a union.
  • The form an is used before words beginning with a vowel, as in an axe, an oscilloscope.
    • It is also used before words which begin with a vowel sound because the initial consonant is not pronounced, as in an hour, an honour, an honest person

  accept, except

  • Accept means to receive ( She accepted his last biscuit.) or agree to (I can't accept the judge's decision).
  • Except means to leave out (Everyone's daft, present company excepted).
  • Notice that the words have opposite meanings.

  ---

  affect, effect

  • Affect is a verb and it deals with action-changing or influencing something (Visiting Ethiopia affected him greatly.).
  • Effect can be used as both as a noun and a verb.
    • As a verb, it is rather formal, and means 'to cause, bring about', as in (He tried to effect a reconciliation between his parents.)
    • As a noun, effect means 'result, consequence, impression' (What was the effect of your action?)

  all ready, already

  • All ready means all (things or people) are ready or set. (We were all ready to leave when it started raining.)
  • Already deals with earlier time. (i was already at work when you called.)

  conscience, conscious

  • Conscience is a sense of morality-being able to tell right from wrong, eg: His conscience failed him when he had to make his own decisions.
  • Conscious means that a person is
    • not asleep, eg: He became conscious only after the lecturer had finished talking
    • somewhat aware, eg: She was conscious of the price of petrol

  fewer, less

  Generally,
  • less is used for quantity,
  • fewer of amount/number.
  • Fewer potatoes, less mush.

  maybe, may be

  • Maybe means perhaps, eg: Maybe I will go, too.
  • May be means could be or might be, eg: She may be able to get here.

  to, too

  To has many meanings:

  direction

  He went to her

  for or of

  The jacket to his suit is in the wardrobe

  in

  There are about four litres to a gallon

  comparison

  Red Rum won, 5 to 3

  part of a verb

  What do you want me to do or to be?

  Too means

  also

  I was there too

  very

  that was too bad. The corrosion was too far gone

  more than enough

  We had far too many people at the party

  
  Back to Top

  ---

  Bibliography

  Dictionaries

  • Chambers Everyday Dictionary, Chambers
  • Concise Oxford Dictionary, Oxford
  • Oxford Paperback Dictionary, Oxford
  • Penguin Dictionary, Penguin
  • Pocket Oxford Dictionary

  Books

  • G. V. Carey, Mind the Stop, Penguin, (a guide to punctuation).
  • H. W. Fowler, Modern English Usage, 2nd ed, rev. E. Gowers, Oxford.
  • E. Gowers, The Complete Plain Words, rev. B. Fraser, Penguin
  • H. J. Tichy, Effective Writing for Engineers, Managers and Scientists, Wiley, 1966.
  • Robert Barrass, Scientists Must Write, Chapman & Hall, 1978.
  • Roget's Thesaurus of English Words and Phrases, revised ed. by Susan M. Lloyd (Longman, 1982).
  • Technical Editing, Judith A Tarutz, Addison Wesley.
  • A Handbook of Writing for Engineers, Joan Van Emden, Macmillan.
  • Writing Technical Reports, Bruce M Cooper, Pelican.
  • Scientists Must Write, Robert Barrass, Chapman and Hall.
  • Effective Writing, Turk Kirkman, Spon.

  A good book to read to enable you to develop constructive study techniques is 'Use Your Head', Tony Buzan. The University library has copies.
  

  Back to Top

  ---

  Printing this Document

  Feel free to send this document to the printer.
  However, be aware that you may get more than you need or want.
  A much better strategy is to
  1. click on the 'File' button in the Menu bar
  2. choose 'Save as'
  3. identify the disk and directory to which you wish to save
  4. click on the down arrow besides the 'Save File as Type' box
  5. choose 'Plain text'
  6. and save the file to disk
  7. (if you don't have a floppy with you, save the file to disk and send it to yourself using email)
  8. later you can load the file into a wordprocessor and print out the parts of the text you need.
  9. Be aware that all normal copyright restrictions apply, ie: you can take a copy for your own use but not for distribution in any form.