Guide to technical writing
From Derek
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.
Contents
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.
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
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 it looks too much like a minus sign. Use the long dash for a pause in a sentence. 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.
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.
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.
