Difference between revisions of "Guide to technical writing"
(→Formal versus informal word usage) |
(→Spelling convention) |
||
| Line 17: | Line 17: | ||
* 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. | * 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, | + | * 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. The rule here is to put both in Google and see which one wins in terms of greatest number of hits. In this example, the spelling "infrared" began to have dominant Google hits and is now clearly the dominant spelling. | * 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. The rule here is to put both in Google and see which one wins in terms of greatest number of hits. In this example, the spelling "infrared" began to have dominant Google hits and is now clearly the dominant spelling. | ||
Revision as of 16:50, 29 June 2013
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 an 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 fir ease of editing.
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. The rule here is to put both in Google and see which one wins in terms of greatest number of hits. In this example, the spelling "infrared" began to have dominant Google hits and is now clearly the dominant spelling.
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 → doesn't, 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
- Tiny → small
- Wonderful → significant
- Fantastic → significant
- Great → significant
- Splendid → significant
- Amazing → significant
- Marvelous → significant
- Beautiful → elegant
- Happen → occur
- Cheap → low cost
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.
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
- Would → will potentially
- Could → may
- 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.
