Difference between revisions of "Guide to technical writing"

Revision as of 16:02, 11 January 2014

This is Derek Abbott's guide to technical writing, primarily for use by his PhD students. But anyone is welcome to use this resource. Each PhD student is requested to go through this page as a checklist when writing a journal article or a thesis chapter.

Introduction

Guidelines for technical writing are on this page. There are no rules for managing this page. Anyone can edit this page and add questions and discussion. It is self-moderating and you can delete and edit anything you like. To resolve conflicts use the discussion page. If you come across your own hints and tips that you think are useful to others, feel free to add them.

Choice of writing package

• We use LaTeX because engineering is a highly mathematical topic, and this is the most professional way to present a mathematical paper. Also managing a very large document, such as a thesis, is actually easier in LaTeX. The overall quality of presentation beats Microsoft Word without question.

• Because LaTeX is a typesetting language, and not a word processor, it is the most efficient way for a journal to convert your paper into a final published form without making any mistakes in translating your mathematical expressions. If you send a highly mathematical paper in Word to a journal, the chances are that your maths will end up with many formatting errors that you then have to fix at the galley-proof stage.

• We use Microsoft Word for administrative matters, writing letters to editors, grant applications, CVs etc. But for technical journal articles and a thesis, LaTeX is the preferred medium. In some cases where we are collaborating on a journal article with non-engineers (eg. biologists) we will compromise and use Microsoft Word for ease of editing between many authors of different disciplines.

• For the thesis LaTeX style file download it from here. You are strongly recommended to use this style file. Six postgrad alumni medal winning theses had use this style file and so it will give you a winning presentation style.

Spelling convention

• We use either American, British, or Australian spelling depending on the requirement of the publisher. In the case of a thesis, because this is Australia, we use Australian spelling.

• In the case where two alternative spellings are allowed, eg. biassing or biasing, always chose the shortest one.

• There are cases where language is evolving and it is uncertain which spelling is out of date and which is acceptable as a modern replacement. For example, back in the 1990s it was unclear whether to write "infra-red" or "infrared." "Infra-red" was the old way to write it, but many people were starting to write "infrared." In order to decide, put both versions both Google and see which one wins in terms of greatest number of hits. In this example, the spelling "infrared" has the most Google hits and is now clearly the dominant spelling.

Punctuation

• In Derek's group we follow all the standard rules of punctuation, except for commas we obey the Oxford rule. The Oxford rule is more logical and it inserts a comma before "and" in the following situation:

Normal comma rule: Apples, oranges and bananas.

Oxford comma rule: Apples, oranges, and bananas.

• In a sentence where there are two commas, you can easily check yourself if the commas are in the right place. The trick is to read the sentence and skip the words between the commas. If the sentence still makes sense then the commas are correct.
• When inserting punctuation treat each mathematical equation as if it is a word. For example if an equation ends a sentence, the full-stop must be on the end of the equation! Remember, equations obey the rules of punctuation as if they are like words. One equation, no matter how long, is like one word.
• Always put punctuation to the left of a closing inverted comma, not the right.
• Full-stops, commas, colons, semi-colons, question marks, exclamation marks, all have no space on the left, but always have one space on the right.
• The dot at the bottom of a question mark or at the bottom of an exclamation point serves the function of a full-stop. So these must be at the end of sentences and there is no need to add another full-stop.

Tone

The tone of your writing is important and it should be:

• Formal
• Dispassionate
• Do not use the passive voice

Formal versus informal word usage

In scientific writing for journals and your thesis, you need to avoid informal words and use a formal equivalent. If you are writing a popular magazine article, then these requirements can be ignored. Here is a list of words to watch out for:

• Remove all contractions, as they are informal. For example, don't → do not, doesn't → does not, can't → cannot
• Don't use the first person, "I" in technical writing, or "my." "We" and "our" is okay.
• Do → carry out; perform; conduct
• Done → carried out; performed; conducted
• Big → large
• Huge → very large
• Enormous → very large
• Humungous → extremely large
• Bigger → larger
• Tiny → small
• Wonderful → significant
• Fantastic → significant
• Great → significant
• Splendid → significant
• Amazing → significant
• Marvelous → significant
• Beautiful → elegant
• Happen → occur
• Cheap → low cost
• Get → obtain
• Some → a number of

Grammar

In Derek's group we try to stick to the convention of keeping everything in the present tense, except when talking about previous work only then use the past tense. This helps to keep the tone exciting and dynamic, and it becomes easier to avoid the passive voice.

An exception is when we are collaborating and publishing in a medical or biological journal. Here, these journals strictly want you to use the past tense for your experiment, but the present tense for your discussion and analysis. Physical and engineering journals accept present tense for your experiment, discussion, and analysis.

Which versus that

• When you are speaking "which" and "that" are interchangeable. This is not true for writing.
• Never insert a comma before the word "that." If you need a comma then remove "that" and replace it with "which."
• When the part of a sentence after "which" is explaining something about the sentence before the "which" then there is a comma before the "which." All other uses of "which" don't have a comma before them.

Derek's golden rules

• Derek's golden rule #1: Never use the words "could," "would," or "should" in technical writing. "Could" and "would" are very weak sounding words, and "should" is too emotionally commanding. Suggested alternatives are:

Should → ought to, is possibly

Would → will potentially, will possibly

Could → may, can potentially

• Derek's golden rule #2: Never begin a sentence with an abbreviation, mathematical symbol, or acronym. All sentences must begin with a real English word.
• Derek's golden rule #3: Nested brackets are forbidden. Although we allow nested brackets in mathematics, they are not allowed in written text.
• Derek's golden rule #4: Try to avoid using brackets wherever possible. Only use them when you have no other choice.
• Derek's golden rule #5: Try to avoid multiple-letter mathematical variables. Rather than inventing a multiple-letter variable, use a single letter with a descriptive subscript. This is always preferred. In cases were multiple-letter variables have become tradition in the literature, such as SNR, then it is okay to use use them. But don't be guilty of making up new ones, because they are evil.

LaTeX tips

• When a full stop ends a sentence, LaTeX automatically inserts a larger than normal space after it. So when you have a full-stop that is not ending a sentence, eg. in an abbreviation, always put a tilde (~) after that full stop. The tilde will then suppress the large space and it also suppresses a line break at that point. This is important, because you don't want a full-stop at the end of a line if it is not the end of sentence.
• Don't get the three kinds of dashes mixed up in LaTeX: (1) - short dash or hyphen, (2) -- medium dash, and (3) --- long dash. Use the short dash for hyphenating words. Use the medium one for a number range. Don't use the short dash for a number range, as that is reserved for a hyphen. Use the long dash for a pause in a sentence (the pause is longer than a semicolon but shorter than a full-stop). Another rule is that there is no space either side of these dashes. But there is a space either side of a minus sign.
• Only single-letter non-bold variables are in the italic math font. Operators, numbers, constants, labels etc. are all in normal font. In a LaTeX equation if you need to force something to appear in the normal font use {\rm ...}.
• Physical units are always in upright font, so can be written outside the $...$ environment.
• There is always a space either side of math operations such as +, -, <, > etc. The $...$ environment takes care of this for you. So always write $a>0$ and not $a$>0, or the spacing will come out wrong.
• If you are inserting Matlab code or computer pseudo-code into a paper or thesis, use the {\tt ...} font.

Mathematics

• Use bold for vectors
• Single-letter non-bold variables are in the italic math font. Everything else in the mathematics is in the regular upright Roman font. The backslash in front functions such as \sin and \cos will take care of this for you. But in other cases, to force the upright Roman font you need to use {\rm...}.
• Avoid using an asterisk to mean multiplication or convolution, in the main text. An asterisk is only allowed to mean multiplication in computer code. To mean multiplication, most of the time just put two variables next to each other. Sometimes you can insert \cdot if you want to be explicit. If you are multiplying raw numbers use \times. For convolution use \otimes. If you really need to use an asterisk for convolution, do not use * but use \ast. The \ast version uses the operator font and is properly centered.
• Remember each equation is considered part of a sentence and obeys the rules of English punctuation. In terms of punctuation, one equation counts as one word, no matter how long it is.

Spacing

• Full-stops, commas, colons, semi-colons, question marks, exclamation marks, all have no space on the left, but always have one space on the right.
• There is always a space between a number and the units. Normally you must create the space with a tilde, in LaTeX, to suppress a linebreak.
• Note the special case that a number has no space after it, if followed by a percentage sign or a degree symbol.

References

• When writing a journal article, always follow the format required by the specific journal.
• When writing your thesis always use Harvard style referencing. This means you cite using author name and year, rather than by a reference number. For a huge document such as a thesis, the Harvard style is preferred by examiners because they can often recognize a reference from the name and year. This saves them from constantly having to check the references at the end. Also Harvard style is much easier to manage in a large document, because the references are all at the end alphabetically. In LaTeX, use \cite as normal, and it is the style file that will create the Harvard style. However, when you refer to the reference itself as a noun you must use \citeasnoun.

How to use bad writing to annoy the hell out of a PhD examiner

Prof. Bob Bogner used to have a list of ways to annoy a PhD thesis examiner. These also apply to journal reviewers. Remember, this is a list of what NOT to do. So make sure you avoid them. I have adapted his original list as follows:

1. Use the word 'this' ambiguously. "The dynamic system goes unstable when the feedback coefficient exceeds unity and then the machine may over-speed and explode. This may be avoided by the use of the proposed design method." Notice that "This" could refer to the system, to the instability, to the over-speed, to the explosion, or to the situation. Be aware that the word "it" also can have the same ambiguity problem.

2. Use "however" as a conjunction. "The coil overheats, however the motor does not catch fire." Try to avoid this. Three correct alternatives are:

"The coil overheats, and the motor does not catch fire."

"The coil overheats, but the motor does not catch fire."

"The coil overheats. The motor, however, does not catch fire."

3. Use "so" as a conjunction. "The train left early so many people missed it." The correct connection is made by the use of "and so", indicating the cause and effect relationship: "The train left early and so many people missed it." A different sense is implied by the construction: "The voltage is low so that users will be absolutely safe." This case is allowed because "so" indicates a purpose for the voltage being made to be low.

3. Use "it's". The word "it's" with an apostrophe should appear nowhere in technical writing. We do not allow contractions, so its use to mean "it is" is not allowed. The case of "its" without the apostrophe is the possessive form. So you use it correctly as follows: "The resistor is connected, and its function is to introduce a voltage drop."

4. Missing or erroneous references to figures. Make sure every figure is refereed to in the text.

5. Make a comparison without the object of comparison. "This thesis presents a better method for designing amplifiers." Better than what?

6. Confuse singular and plural words. Tricky cases to watch out for are:

Hypothesis vs. hypotheses

Medium vs. media

Phenomenon vs. phenomena

Criterion vs. criteria

Thesis vs. theses

Datum vs. data

Die vs. dice

Focus vs. foci

Locus vs. loci

Quantum vs. quanta

Polyhedron vs. polyhedra

Radius vs. radii

7. Treat singular concepts as if they have graduations. "The parameters have an improved level of optimality." Words such as "unique", "optimum", etc. do not have gradations. Something is unique or it is not. Something is optimum or it is not. It is like virginity.

8. Use the word "hope" or "hopeful". These types of words are meaningless in scientific writing and are completely banned. Do not use them at all. "We hope our model is an improvement over Shannon's model" should be "Our model is aimed at providing an improvement over Shannon's model." Also, "Hopefully the voltage will not be excessive" implies that the voltage hopes like a person. A better form is: "It is anticipated that the voltage will not be excessive."

9. Use capitals incorrectly. This can really annoy the reader. Never use block capitals for emphasis. The rules for capitals in English text are:

Capital at the beginning of a sentence

Capital for proper nouns (i.e. named things)

Capitals for acronyms

Capitals for Section 1, Figure 1, Equation 1, Table 1 etc, because you are naming those item. When you are generally referring sections, figures, equations, tables etc it is lower case because you are not naming a specific one

Capitals in title case for any part of a reference that is in italics

Capitalize the first letter of all German nouns when referencing a paper in the original German

10. Omit the subject of a participle. "Making the insulation thin the strength is too low and it may rupture." Who or what is making the insulation thin? The construction implies that the strength made it thin. Perhaps the author meant "Making the insulation thin causes the strength to be too low and it may rupture." Who can tell what the author meant if the words are ambiguous?

13 Use "/" in written text to mean "or". This is sloppy and is banned.

14. Use the phrase "as such". This leads to imprecise sounding sentences and is best to be avoided.

Why all the above rules are important for your PhD thesis

On a trip to the University of Cambridge, Ken Moxham from our Civil Engineering department once saw the following passage: "Because of the impracticability of an examiner's establishing the details of the conduct of the research, the care with which a thesis is prepared will be taken as prima facie evidence of the care with which the research has been carried out."

Back

• Back to MyUni
• Back to Derek Abbott's homepage
• Back to EEE Department page
• Back to the University of Adelaide homepage