Purpose
The School of Electrical and Information Engineering is committed to the goal that a high standard of written and oral communication is attained by its graduates. To this end, the School has developed its Communications Manual both as a guide to producing various types of documents and oral communications. Copies are available from the School's Reception at a modest fee. This web page contains supplementary information to Report Writing and Oral Presentation: A Communications Manual for the Engineer Revision 4.0 December 1999.

Contributions to the development of this page and the Communication Manual should be e-mailed. Suggestions for useful references and links are most welcome. Keep them coming!

Organisation
This website contains two principal sets of information:

• Supplementary Information to the Comunications Manual. This material will be incorporated into the next edition of the manual. Items are identified and ordered accoring to the applicable section of the manual. The manual defines the School's standards for technical communication. The supplementary information forms part of the standard.
• Useful Information to Assist Writers and Presenters.

Copying another student's work is also plagiarism. Copying another student's work with his or her knowledge or permission to pass of as yours is termed collusion. Similarly, the person who permits copying is guilty of collusion.

Plagiarism may constitute a criminal offence under Copyright Law. Plagiarism and collusion are viewed as a serious breaches of academic and professional ethics. Wits sees plagiarism and collusion in a sufficiently serious light as to require every teacher encountering such a case to report it to the Legal Office for the possible institution of a disciplinary hearing against the student(s) concerned. (See General Rule 15.10.) Where students are found guilty of plagiarism, the penalties imposed are usually severe.

In plain English, the total unacceptability of plagiarism means that:

• You must not simply copy material, including text and diagrams, from other sources into your work.
• You may make limited, properly acknowledged, quotations from references if, and only if, you follow the conventions for text quotations described in the School's Communication Manual.
• You must not in general copy diagrams from references. It is always better to adapt your own diagrams from the literature, omitting or de-emphasizing unimportant features, emphasizing the features of particular relevance to your work and showing your contribution to understanding of the material. The original must still be acknowledged. For example: Adapted from Smith [10].
• You must write the part of your text referring to the reference in your own words. You may sumarise or paraphrase - and even criticise - the original author's work. Citations must be inserted.

Plagiarism Home Page for more information
For a full treatment of the problems of and cures for Plagiarism

Index

Effective Literature Review
Always remember that the objective is to obtain material that supports the work at hand. The following stages constitute an effective literature reviewing method.

• Firstly, you must have a problem statement or research question in mind, even if it is not yet properly formulated.
• Obtain reference material: from archival and other sources including the Internet.
• Read and comprehend references: too often the mere possession of a copy of a reference is considered adequate scholarship. It is essential that each reference be read in adequate depth. Some works may be rejected after skim reading. Any reference actually used must be carefully read and digested.
• Organise and record information: Enter references into a properly formatted list. Summarise the parts of reference relevant to the work.
• Evaluate information: What is the relevance of the material? What is the standing and credibility of the material?
• Draw conclusions: What does the reference contribute to the solution of the problem?
• Document relevant material: Write sentence(s) or paragraphs in your own words for your document, citing references. See effective referencing.

The hypothetical reference list look like this:
[11] M H. Sweet and S.A. MacGonegal, “Simulation of Widget Production Processes”,   Timeless Inc., Frankfurt, 1993.
[12] Denniss, D.W. and. Baker, D.A., Widget Distribution  Networks and Their Topology, James Hall & Sons Ltd, London 1997.
[13] As per search done using Altavista Advanced Search 11 April 2002.
[14] www.google.com
[15] My knowledge on the subject.
Index

If a reference has a wider scope than the current sentence the scope should be clearly indicated. For example:
      We summarise the approach of Mugg and Bean [11]. They address the problem of .... Their work is based on the assumption ... We rely on their third result, namely ......

Don't put a reference at the begining of a sentence. For example.
       [10] discusses pseudo-widget dynamics.
Rather write:
       Bloggs derives the theory of  pseudo-widget dynamics [10].
Index

Good Practice

1. Standards documents published on the Web-sites of reputable standards bodies can generally be quoted with confidence.
2. Check all the web references when the paper is complete for submission to the conference or journal. Do not rely on references that were accessed one, three, six, ...  months ago.
3. Restrict web references to white papers, standards, tutorials and similar documents.

1. Simply quoting the result produced by a search engine without going to the reference itself and evaluating it.
2. Restricting the reference to the URL. Many sites are complex and the document must be identified exactly. At least the document title and the organisation behind the website should be quoted. If the document has an author, that's better still.
3. Quoting summaries of inaccessible documents (the full document may contain a different message!). Don't assume that the person who wrote the summary did a good job!
4. Quoting documents that are not available to any web user, for example requiring a password or (high) fee.
5. As far as possible, do not use press releases or other ephemera as references unless the context justifies it: for example in a paper on how ephemeral press releases are.
6. Do not cut and paste text, pictures and diagrams from web references. There could be copyright implications. Rather quote and acknowledge. See Plagiarism. In any event, cutting and pasting usually means that the material is never processed mentally by the cutter and paster!
7. Do not give URLs which contain script or search parameters, for example: http://whatis.techtarget.com/wsearchResults/1,290214,sid9,00.html?query=Provider+Edge+Router

or more impressive still:http://www.google.com/search?as_q=&num=10&hl=en&ie=UTF-8&oe=UTF-8&btnG=Google+Search&as_epq=Best+of+breed%2C+carrier+grade&as_oq=&as_eq=&lr=&as_ft=i&as_filetype=&as_qdr=all&as_occt=any&as_dt=i&as_sitesearch=&safe=imagesOnly Always use URLs that resolve to a file or folder, for example http://www.ietf.org/rfc/rfc1661.txt.

A possible exception to this rule occurs in the case of detailed design reports. In that case, the supervisor may require copies of data sheets to be included in internal reports to create a complete design file. This practice should not be permitted in public documents.
Index

• Migrate to LaTeX early: there is a learning curve to being able to exploit the power of LaTeX.
• Adopt a development environment such as TeXnic Centre.
• Develop a set of diagrams using a quality drawing programme, saved in EPS format. (A second objective is related to avoidance of pagiarism. The author should never cut and paste diagrams without the explicit permission of the copyright holder. Rather, the author should develop diagrams, which may be based on standard or other authors drawings, but should be adapted and enhanced to show the points that the author wants to bring out.

Insert references into BibTeX data files as they arise. Ensure that the most appropriate type of reference is chosen and that the title and author fields are correctly formatted. Check the validity of the entry by producing a reference list and careful proofreading.

"As a writer, I can tell you that trouble in writing clearly reflects troubled thinking, usually an incomplete grasp of the facts or their meaning."
                                                            B.W. Tuchman, Generalship, in Practising History, Papermac, London, 1981.
"Talent helps, but exposure to books is necessary. Great writers are great readers."
                                                            Zakes Mda, giving advice to aspirant writers, Star, Johannesburg, 16 October 2002.

Difficulty with writing has two principal roots. The obvious reason is inexperience or lack of expertise in writing. A second and often important cause is the author not understanding the subject of the document sufficiently to create a logical exposition. To illustrate the latter, consider the problem of explaining the concept of time [1]. St Augustine of Hippo remarked that he knew well what time is - until someone asked. Then he was at a loss for words. How often we all have had that same experience.

We have a circular phenomenon which could be either virtuous or vicous. Writing helps clarify ideas. A countermeasure to inability to write because of an ill-formed understanding is therefore starting to write, no matter how imprfect or painful.

1. P. Davies, The mysterious flow, Scientific American, vol 287, no 3, pp 24-27, September 2002.
Index

Effective use of figures, tables.
Refer to figures or tables when the part of the text that relies on or explains starts. Conversely, do not give the whole explanation and then refer to the figure as if an afterthought.

In the text, walk through the relevant parts of the diagram. Don't use phrases such as  " .... it may be seen from the figure that ... ".  Rather refer to specific, clearly identified features in the figure. For example: "Terminal A shown in figure 6.2 sends a connection request to the Network Interface." is an acceptable form if both objects are clearly identified in the figure.
Index

The general rule about using clip art to decorate documents or presentations is: Don't!
Index

• Making the abstract Section 1 of the report: the abstract must not be numbered and must be placed after the title but before any other parts of the document.
• When writing the introduction, relying on information given in the abstract.
• Not using Checklist 7. (It always seems easier afterwards.)

S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, Internet Engineering Task Force, Request for Comments 2119, March 1997. Available at www.ietf.org

Must or shall or is required  means that the entity referred to is an absolute requirement.

Must not or shall not means that the entity referred to is absolutely prohibited.

Should or [is] recommended   means "`that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course."'

Should not or [is] not recommended  means "that here may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full  implications should be understood and the case carefully weighed before implementing any behavior described with this label."

May or [is] optional  means that an item is truly optional.

A related problem word is can which when used properly indicates a capability! The word can should not be used in lieu of may. See below for its other regular misuse. The best thing to do to can is can it!
Index

1. Find every sentence beginning with "It .." Replace the "It", inserting the actual entity referred to.
2. Find every sentence beginning with "This ...." without an entity contained in the previous sentence after the "This".
3. Find all instances of "will". If the sentence is not a prediction, the present tense is appropriate.
4. Check all past tense verbs. If the sentence does not refer to something that happened in the past and is not ongoing, the present tense is appropriate.
5. Find all instances of "can be": the simple "is" or "are" usually conveys the meaning. See another comment on "Can".

In typesetting, a point (pt) is a unit of length, for which there are several definitions.

The Didot (European) point  = 0.3759 mm
The Anglo-Saxon (i.e. English and American or ATA) point  = 0.3514598 mm
In LaTeX, one point = 0.3514598035 mm = 1/72.27 inch
In Postscript, one point = 0.3527777778 mm = 1/72 inch

In LaTeX point font sizes are derived from three normalsize values, 10 pt, 11 pt and 12 pt. Larger sizes are available in steps described as \large \Large \LARGE  \huge and \Huge. Reducing size is obtained with the commands  \small, \footnotesize, \scriptsize, and \tiny. The resulting sizes in points are given in Table 5.3 of the Not So Short Guide to LaTeX_2e

Are sizes consistent when the font is changed?
Changing the font has unexpected consequences on the resulting character size. In the many fonts available in Microsoft products the height and average width varies. For example, characters in Arial are 10% taller and wider than in Times New Roman of the same point size. Tahoma is the same height as Arial but wider or narrower on the average in different programmes. In LaTeX, San Serif is the same height but narrower than Roman type of the same point size.

This browser also produces different results. Look at the same sentence in three serif-type fonts:

This is a test sentence for LaTeX, Word, Powerpoint and this browser in the Roman type.
This is a test sentence for LaTeX, Word, Powerpoint and this browser in the Book Antiqua type.
This is a test sentence for LaTeX, Word, Powerpoint and this browser in the Garamond type.

This is a test sentence for LaTeX, Word, Powerpoint and this browser in Arial type.
This is a test sentence for LaTeX, Word, Powerpoint and this browser in  Arial Narrow type.
This is a test sentence for LaTeX, Word, Powerpoint and this browser in Tahoma type.

To see the corresponding effects open these Word, Powerpoint and Postscript Output from Latex files. The last document shows how LaTeX allows many font distinctions to be made with only a few basic font types (Roman, Sans Serif and Typewriter). A short file to see the effect of printing from a browser on fonts is available.

Line Thicknesses in Points
Line thicknesses are sometimes specified in points. Printer resolution is expressed in dots per inch (DPI). It is often useful to reckon line thicknesses in dots. At 600 DPI, a 1 pt line is 8.333 dots thick.
Index

Plus-minus, +/-: used to mean approximately. For example,  "The plane's altitude is +/- 1000 m above sea level". The -1000 m alternative is rather disastrous. The correct usage of +/- is to indicate a tolerance or error range, for example, "The clock frequency is 8 kHz +/- 2 Hz", meaning that the frequency lies between 7998 and 8002 Hz. The abbreviation for approximately is ~ or ca (short for circa, the Latin for around).

Zinc: used to mean galvanised sheet steel, for example roofing sheets. While the element used to protect the steel in the galvanising process is zinc, the dominant constituent is steel.

A frequent shortcoming in student reports is the inclusion of items from the learning process. For example, in a design report, a student wrote "It is important to identify the design requirements". An engineer in practice would not do this but would write the identified design requirements, together with any relevant background, reasoning and sources of information. In the learning situation, we would judge whether the student realises the importance of identifying design requirements by observing the result of the student's problem identification, not by the student telling us that it is important.

There may however be cases in which the student is explicitly rquired to report on the learning or work process. For example, if the assignment is to write an exposition of the design process, the statement "It is important to identify the design requirements" may be entirely appropriate.
Index

The use of SMS abbreviations is creeping into technical writing. The position is simple: SMS abbreviations are unacceptable in any form of formal writing.
Index

This is very tongue-in-cheek, but may prove to be a good example of how not to write reports.

            William Safire's Rules for Writers:

Remember to never split an infinitive.  The passive voice should never
be used.  Do not put statements in the negative form.  Verbs has to
agree with their subjects.  Proofread carefully to see if you words
out.  If you reread your work, you can find on rereading a great deal
of repetition can be avoided by rereading and editing.  A writer must
not shift your point of view.  And don't start a sentence with a
conjunction.  (Remember, too, a preposition is a terrible word to end a
sentence with.)  Don't overuse exclamation marks!!  Place pronouns as
close as possible, especially in long sentences, as of 10 or more
words, to their antecedents.  Writing carefully, dangling participles
must be avoided.  If any word is improper at the end of a sentence, a
linking verb is.  Take the bull by the hand and avoid mixing
metaphors.  Avoid trendy locutions that sound flaky.  Everyone should
be careful to use a singular pronoun with singular nouns in their
writing.  Always pick on the correct idiom.  The adverb always follows
the verb.  Last but not least, avoid cliches like the plague; seek
viable alternatives.

We offer a real time, carrier-grade, standards-based, best of breed product, offering a massively scalable, feature-rich and cost-effective solution to manage all components of a mission-critical  application ecosystem in which we leverage our deep domain expertise to offer a superior value-proposition to customers, through productivity-enhancing, ease of use, reliability, and extensive customizability, powering solutions in many market segments, enabling superior solutions with rapid time to market advantages.

Here are two samples of paragraphs from an introduction to a paper. The left hand column is the original and the right hand column is the result when the paper had to be shorthened for publication elsewhere. All that was done was to look for economy of expression. The line count diminished by 20%. How meaning much was lost in the economical form?
 

Index

Acronym: a pronouncable word made up from the inital letters of the words making up a name, adopted into the language, written with an initial capital and lowercase.
Examples: Radar = Radio Distance and Ranging; Laser = Light Amplification by Stimulated Emission of Radiation; Cosatu = Congress of South African Trade Unions; ....

Abbreviation: a shortened form of a word or phrase, including use of initial letters to represent the full name of organisation, object, concept, ...
Examples:  Op-amp, exam, e.g., TV, ITU-T, PSTN, N (=North), ...

Mnemonic: a formula for aiding memory.
Example: CIVIL: In a Capacitor current (I) leads Voltage  but I lags in an inductor (L).

Some abbreviations will never become acronyms, for example FPLMTS (Future Public Land Mobile Telecommunications System) - which fortunately has been supplanted by Third Generation Mobile, abbreviated 3G (pronounced three gee). Is 3G an acronym?

Where would you put Graphical User Interface, abbreviated GUI but pronounced gooey? How would you classify SMS (Short Message Service) as sent by cellphone (an in particular, the verb to SMS)?

Index

We note (in the Manual) that commas are used to separate items in a simple list in a sentence. For example, "The amplifier consists of a housing, a preamplifier stage and a power amplifier".  A valid (but not universal) practice is to put a comma before the "and". The sentence would read: "The amplifier consists of a housing, a preamplifier stage, and a power amplifier". This usage is known as the Oxford comma.

More on the colon.
In the Communications Manual, we explain the use of the colon to separate structure in a sentence where the second elaborates on or explains the first. The second important use of the colon it to introduce a list as the example shows.

The meal is structured in three courses:

• A first course consisting of butternut soup or smoked salmon;
• A main course with choice of six dishes; and
• A low-calorie dessert.

In a definition a colon is read as "means", for example

Curriculum: a group of courses that leads to a qualification.

Are there rules on punctuation?
The English language has grammatical rules but does not define how punctuation should be performed. Punctuation serves two purposes: firstly to help bring out the meaning and  impact of sentences; and secondly, to assist with the rythm of the sentence, if read out aloud. Current practice is to keep punctuation to the minimum necessary to serve these purposes.
Index

Title Slide
When presenting the title slide, it is often better to say "My presentation is on ...." rather than "The title of my presentation is (and then repeat it verbatim)."

Getting Going
The Outline, Overview or Agenda Slide, usually the second slide should not have too many points. As a broad guide keep to the following approximate limits:

10-15 minute Presentation, 4-5 points (expanding to one slide per point)
15-20 minute presentation, 6-7 points (expanding to 1.5 slides per point on average)
20-30 minute presentation 8 points (expanding to 2 slides per point on average)

When presenting this slide, don't say; "The outline of my presentation is...". Rather say "This presentation first .... then, This leads to... ".

The purpose of presentation or problem statement must come out early in the presentation. One of many ways of conveying the purpose is a dedicated slide befor or immediately after the Outline.

Conclusion Slide
The conclusion slide must bring closure to the presentation. The conclusion must be more that a backward looking summary and must clearly express the findings of the work.

Using animation
Powerpoint provides the possibility of animation of slides. At a simple level, bulleted items can be made to appear in sequence. Diagrams can be built up by making groups of drawin objects appear in sequence. At a more complex level, audio and video clips can be inserted. Regrettably, the power of animation is frequently misued and the presentation is not enhanced. The folllowing guidelines support restrained yet effective use of animation.

In the case of bulleted lists and diagrams:

• Use animation when developing a complex idea.
• Restrict the effect to "Appear". Other effects in which the item or drawing group moves into place are often distracting (and can take time on a slow PC).
• In general, do not dim earlier items.

Backgrounds (Designs)
Conventional wisdom holds that it is best to use light text (white or yellow) against a dark background, usually blue. However, with the availability of high-brightness data projectors, dark text on a light (while) background is in many cases more legible.

Using a Powerpoint Design which gives a patterned background to text or diagrams has possible adverse effects. Legibility may be reduced.  The design may obscure material when hardcopy of slides is printed.
Index

Difficult words and phrases not listed in Appendix A
The Appendix to A communications Manual for The Engineer lists a number of troublesome words and phrases that are best eliminated from any form of technical writing. Here are some more ......

It should be noted that ...
A lot of work has been done
Above mentioned, aforementioned
.... can be anything ...
needs to be  (meaning must)
sort out (meaning solve the problem)
... is when ....
Maybe ....  (meaning that something is possible)
There are ...
This means ....
This is because ....
That is (sentence starting with)
...provides us with ...
However, while .... (don't use both)
It can be seen
.... it may be seen ...
 .... some kind of ...
 .... : in other words (colon means in other words)
  ... is what ...
cause problems,   can be problematic

The European Commission has just announced an agreement that English will be the official language of the European Union, rather than German (the other possibility). As part of the negotiations, Her Majesty's Government conceded that English spelling had some room for improvement, and has accepted a 5-year phase-in of new rules which would apply to the language and reclassify it as EuroEnglish. Thus, the agreed upon plan is as follows:

• In year 1, the soft 'c' would be replaced by 's'. Sertainly, this will make the sivil servants jump with joy. The hard 'c' will be replaced by 'k'. This should klear up konfusion and keyboards kan now have one less letter.
• There will be growing publik enthusiasm in the sekond year, when the troublesome 'ph' is replaced by 'f'. This will reduse 'fotograf' by 20%.
• In the 3rd year, publik akseptanse of the new spelling kan be expekted to reach the stage where more komplikated changes are possible. Governments will enkourage the removal of double letters, which have always ben a deterent to akurate speling. Also, al wil agre that the horible mes of  the silent 'e's in the language is disgrasful and they should eliminat them.
• By year 4, peopl wil be reseptiv to lingwistik korektions such as replasing 'th' with 'z' and 'w' with 'v' (saving mor keyboard spas).
• During ze fifz year, ze unesesary 'o' kan be dropd from vords kontaining 'ou'  and similar changes vud of kors be aplid to ozer kombinations of leters.

"Writings are useless unless they are read, and they cannot be read unless they are readable."
                                                                 Theodore Rooseveldt, 1912

"Research is endlessly seductive; writing is hard work."
                                                            B.W. Tuchman, In Search of History, in Practising History, Papermac, London, 1981.

"What is in the mind does not readily appear on the page."

"You don't know how to do it [write] until you have the scars."
                                                           A Masters Student.
Index

Resources
A good set of references on research and writing (Computer Science oriented but generally good)
How to give a bad talk

Index

This product information originates from http://www.useit.com/alertbox/9612.html, a 1996 page called Why Frames Suck. Apparently Frames Still Suck in 2002 according to http://www.voltapublishing.com/netgains/features/frames/  Also interesting is the late 2001 item "Why Frames Are Not Supported at MIT" http://web.mit.edu/cwis/frames/ For more on frames, just ask Google to find the phrase "Why Frames Suck"

I tested the assertion dating from 1996 that Frames hamper search engines. I set Google to find some characteristic phrases in two frame based pages www.ecsa.co.za and satina.ee.wits.ac.za. Google had no problem with either. I don't think that this finding diminishes the other reasons for not using frames.
Index