Writing technical reports

Intro

This document is really a collection of things that I should remember when I'm writing reports myself. If someone else thinks it's useful then they can use it but this is all just guesswork really, based on what I find easiest to read and the main mistakes I find myself making. As with everything, it's a work in progress — and I'll be very welcoming of comments or additions.

More complete/official references on good writing style are, for example, "The Chicago Manual of Style" (for technical matters) and George Orwell's famous "The Politics of the English Language" for good advice on prose stylings. The little Penguin reference book "Mind The Gaffe" is an entertainingly source of English language obscurities.

Good/correct English

It's a sad truth that not enough people know how to write good English. I won't claim any particular aptitude for it myself, but here's a few collected aspects of the language which are reasonably non-subjective:

• Avoid unecessary capitalisation: not everything is a proper noun! For example, in writing about scientific subjects, someone might mention ``Theoretical Physics''. The capitals aren't necessary unless this is in the title of some paper or similar --- even then a typical style is to only capitalise the first word and proper nouns.
• Americanization: `s' versus `z'
• Double and single quotes
• Using SI units: correct spacings, italicisation (i.e. don't), space between number and unit.
• Minimise hyphenation, subclauses/caveats and parentheses, abbreviations
• Acronyms
• Sentence ordering
• Line length (typesetting)
• Active and passive voice; tenses
• Sentence and paragraph length: breaking up the document
• "as follows"
• Punctuation
• Know your ()s: parentheses, brackets, braces, angle brackets
• Don't use possessives and try to define an acronym at the same time; for example, ``the Ring Imaging \v{C}erenkov Detector's (RICH) radiator gas'' works much better as ``the radiator gas of the Ring Imaging \v{C}erenkov Detector (RICH)''.
• Know your hyphens from your m-dashes, n-dashes and minuses — use them in the appropriate places and, perhaps more importantly, use them consistently.
• Split infinitives and terminating prepositions; both sound rather silly so try to avoid them. Don't create a monstrosity on the way, though: a "correction" of the title of U2's "I Still Haven't Found What I'm Looking For" (which sports a terminating preposition) would be "I Still Haven't Found That For Which I Am Looking". That's ridiculous, so be prepared to bend/break this "rule" if the result is going to be similarly awful.
• Sectioning: a delicate balance
• Obsfucation: "in order to..." -> "to..."
• "onto" is not a word: "on to" is the correct version. The same goes for "alot": it should be "a lot"!
• "parameterise" or "parameterize" are both valid (but be consistent!). "parametrise" and "parametrize" are not — the word derives from "parameter" and so the "e" has to be retained.
• Abbreviations like "e.g.", "i.e.", "etc." and so on should be used sensibly (which means infrequently) and should not be italicised. Get the dots in the right place: "cf." only has one dot, for example.
• Parenthetical statements or quoted statements at the end of a sentence or phrase; if a comma or full-stop appears immediately after a bracketed or quoted statement, then the punctuation is often absorbed into the preceding block, even when the semantics of such behavious don't make sense. It's a typographical rule, intended to make the sentence's appearance more pleasant, rather than a semantic construction. See ``The Chicago Manual of Style'' for more info on this sort of thing.

Mathematical specialities

Mathematical variables should be typeset in italic text. Anything else (a label on a variable, or text for example) should be typeset in roman (upright) text. Operators are often set in a calligraphic font but this is largely left to the discretion of the author. Group names are set in an upright mathematical font and set names are often in ``blackboard bold'', a style which uses doubled vertical struts.

Scientific specialities

In high energy physics applications, particle names should be typeset in an upright font --- unless the particle is being used in an equation in a context equivalent to a variable. Most of the time, they are not variables, so don't italicise them!

That's all, folks

If you've got any comments, please address them to Andy Buckley via www.insectnation.org.