Technical writing tips

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. SeeThe Chicago Manual of Style'' for more info on this sort of thing.

Avoid using a lot of parenthetical constructs and footnotes. If it's important enough to mention at all, can't you rewrite to give it a sentence of its own. Note that footnotes often draw attention to themselves, rather than the opposite, and that parentheses make it harder to read and understand the interrupted sentence. Try phrasing your sentence "backwards" --- does it work better now?

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.

Writing a PhD thesis

This is just another of my typical brain-dumpings, based on things I've learnt the hard way while writing my own PhD thesis. As a result, it's not gospel, it may just be my way of doing it and (perhaps most importantly) it's not guaranteed to be right, especially since I've not finished yet! LaTeX issues

* Make a macro for everything... standardise on things like the symbol you're going to use for a given semantic

object e.g. \efficiency for efficiencies. * Use the booktabs and caption packages to make your tables and captions look decent. The default appearance of TeX/LaTeX tables is appalling. * Use the SIunits package for typesetting your units: it gets the spacings right and does other nice things like using upright mu glyphs for "micro" prefixes. If you're doing high energy physics then you might like to go and get my hepunits package from CTAN to do all those pesky GeV/c2 etc. properly. (You may also be interested in hepnames and hepparticles and, well, anything else I've written on there :-) * Don't be afraid to write your own packages and document classes: they're a good way to store the project-specific macros. Try to put more generic macro definitions in more abstract packages and then you can re-use them. For example, I have sets of packages which do math typesetting, which are then re-used in packages for HEP typesetting, which are then re-used for packages specific to my work. These are then used for writing papers and talks as well as for my thesis: the specific thesis package requires them to work. * Use the AMS mathematical modes rather than the raw LaTeX ones. Use subequations and split environments (among others) to get the equation numbering right. * Don't leave blank lines between text and a displayed equation unless you're really making a paragraph break. Putting a commented (%) line between text and equation keeps the code looking nice. And don't forget to punctuate your equations and to use \noindent at the start of text which comes after a displayed equation where there's no paragraph break. * Cross references should always group strongly. For example, there should never be a line or page break in the middle of "Section 5.4". Use a non-breaking space to achieve this: ... Section~\ref{sec:MyRef} or define an appropriate set of macros to help. egrep can help search for missed examples of this, e.g. egrep -n --color "\\Figure$|\\Equation$|\\Equation~\\ref|\ \\Chapter |\\Chapter$|\\Section |\\Section$|\\Page |\ \\Page$|\\Table |\\Table$" .tex which I use since I've defined a set of dumb \Section etc. macros to keep the references consistently formatted (and easily changed). * Another convention to decide on is whether or not to leave a space between words and the square brackets of a citation. Richard Batley mentions that he favours a half-space which is perhaps most easily enforced by re-defining \cite with \let\OldCite\cite \renewcommand{\cite}[1]{\mbox{!!!\OldCite{#1}}} and using egrep to ensure that \cite is always called with a space in front of it: egrep -n --color "^\\cite| \\cite" .tex

Stylistic issues

* Cut out pretentious bits as you proof-read. If you put a sentence in just because it shows how much you know but

it doesn't add anything to the point being made, then removing it will improve the work. We all do it, don't worry :-) * Keep it simple. Reduce sentence lengths, don't use sub-clauses, avoid parentheses and colons where possible. Try to be elegant and expressive! * Punctuation in an itemize (bullet point) block should be consistent. A good convention is to introduce the block with a colon, to end each but the last point with a semi-colon and to have a semi-colon followed by "and" for the second-last point. Start each bullet point with a lower case character. * Be consistent in how you list units in tables and on plot axes. Noting the units in square brackets is common and avoids the problems assoiated with normal parentheses or (particularly) separating with an oblique, which tends to look like a mathematical division. * Establish certain conventions like whether you'll use "ise" or "ize" endings for words like "factorise"/"factorize" and check at the end with a grep over your *.tex files. Check for these along with common mis-spellings in your final draft, again using grep or aspell. For really commonly-used conventions, think about making a macro for it. * And finally, remember to spell-check it! aspell is an excellent utility for this on Linux and it has some understanding that it shouldn't touch LaTeX macros.

That's all, folks