A Guide to Document Style

A scientific experiment is not complete until the results have been published. Therefore, to do science, one must also write science. Realising this, scientists should weigh the words in their manuscripts as carefully as they weigh the reagents in their laboratories.

Robert A. Day (1989)

Scientist take great care when designing an experiment or developing computer code to avoid inconsistencies in detail. Often the same result could have been obtained from a ill structured code or bodged apparatus. The same is true of a piece of technical writing. The reader can make sense of a poorly punctuated sentence or get the idea from a poorly scaled plot. However good writing like good science demonstrates a clarity of thought and expression that aids the flow of knowledge.

In bothering about the detail in writing a scientist demonstrates a level of accuracy that reflects on his or her efforts in conducting the scientific work itself. Some warnings ensue. Often one person's detail is another's pedantic point. While there is no absolute definition of what is correct. This doesn't mean there is no need for rules. These rules may be modified by an author. However if this is done it must be done consistently. An obvious example is in the use of units for a quantity. It would be unhelpful to the reader if the author vacillated between mks and imperial units in a text.

The purpose of this guide is to provide a ready reference for making consistent choices when constructing a document. Making these choices once allows the writer to concentrate on the substance of the work rather than the flummery. Of course any style guide is exactly that a guide. In making choices I have mostly followed

• University Press, The Chicago Manual of Style, University of Chicago Press, 2010,
• R.M. Ritter, The Oxford Style Manual, Oxford University Press, 2003,
• New Zealand Government Printing Office, Style Book, Government Printer, 1981.

One of the reasons I have prepared this guide is because these sources are not always definitive, especially for highly technical writing. Another reason is that these sources occasionally disagree so that a choice has to be made between different recommended styles. In making a choice the three principals I have applied are; to maximise clarity, to be consistent and to follow commonsense.

The following sections (currently a work in progress) describe my style preferences when preparing written work.

• Layout of a Page
• Structure of the Text
• Writing Style
• Punctuation
• Spelling and Grammar
• Abbreviations
• Numbers and Units
• Mathematics
• Tables and Figures
• References
• Proofing