11/10/2013

Writing format / Style guide

As I write my thesis I keep coming up with questions about the style, layout and formatting that I should use. In many cases I doubt there is a right or wrong answer to the questions I'm asking, however I need to make a decision either way, and be consistent throughout my document. Therefore I've decided to start noting down the questions I'm coming up with and the direction I'm taking, ideally along with reasoned arguments as to why. Hopefully this should serve as a reference for me down the line.

Double spacing after full-stops?

I vividly remember being taught at school to double space after a full stop and single space after a comma, colon or semi-colon. This is a throwback to the days of using typewriters and it is widely regarded as no longer needed. Although it sounds like a slightly larger space can help with readability, modern proportional fonts and processing tools allow for this anyway. The Wikipedia page gives a lot of details on this.

I believe LaTeX can (and does) adjust spacing after a period anyway.

Title case?

What words should be capitalised in a title (e.g. a chapter/section/subsection heading)? "Title case" refers to the practice of capitalising all words in the title except for some subset of short or unimportant words. However what the subset is and whether title case should be used at all does not seem to be clearly defined. Once again the Wikipedia page kicks off discussion on this. It seems that several major publications use sentence case for titles. It seems that its main motivation is as form of emphasis, however it is argued that with the use of modern digital fonts emphasis is more easily added in other ways and that sentence case is easier to read.

Some contributors suggest using title case only for main titles, such as the title of the book and possibly chapters, but using sentence case for lower level headings. I will use title case in this manner, for the title of my PhD and for the chapter titles, but not elsewhere.

Capitalising references?

Throughout my document I make references to other sections and chapters, as well as to figures and tables. Of course I link these properly in my LaTeX source so that hyperlinks are formed, but should I capitalise the word section/chapter/figure/equation? It seems that most, but not all, scholarly articles choose to capitalise in these cases; the argument being, I think, over whether it behaves as a proper noun or not. This raises the question of whether "Page" should be capitalised in cross-references, this would appear very strange and this style does not appear to be in use anywhere. A possible explanation for this is that figures, chapters, etc are 'intentionally' named, whereas pages are not, although this seems somewhat unsatisfactory.

I will capitalise all references except for pages (which I do not expect to use) to fit with the most common useage.

Company, brand and product names?

There does not seem to be a common style in use for formatting these. Most commonly they are presented in standard body text with whatever capitalisation and punctuation the brand commonly uses. At most there may be some specific rules relating to capitalisation for certain publications. However in reading heavily technical work I find that confusion can often arise between technical terminology and product details, therefore it would make sense to be able to show the difference in some way. For example consider the sentences:
" The PID controller is simulated using a Matlab model. The ABB controller is simulated using a parametric model"
Here both "Matlab" and "ABB" are product and company names respectively, whereas "PID" is a technical acronym and "parametric" is a technical term explaining the simulation type. I doubt this distinction would be obvious to anyone unfamiliar with the terminology.

In order to assist with this I would like to apply some formatting convention to highlight company, brand or product names in the text. I have seen one dissertation that used small caps to denote products. This seems to work well as I am not using them for anything else in my document, although it is slightly unfortunate that acronym names do not stand out in this way. 

I am not fully decided on the best way to proceed with this at present.

Indenting paragraphs?

Separating paragraphs in some way to prompt a slight pause whilst reading seems like a sensible writing style. The most common technique for this in printed material is to indent the start of paragraphs, although alternatively an increase in line spacing may be used. As a pause is not required at the start of a new section (or rather, that pause has already been prompted) an indent is typically omitted.

This standard in online material seems to be to use "block text", that is no indents but an increased gap between paragraphs. This makes some sense as there is an infinite space available and there is no confusion over paragraphs breaking across pages

I will be indenting printed paragraphs other than the first and using block text in online materials.

Serif or sans-serif?

Although the jury seems to be out on whether serif fonts are actually any better for print reading, I went with convention and chose a serif font for my thesis.

Table format

As far as possible I followed the excellent recommendations in the booktabs usage guide.

Unit format

I'll be trying to stick with SI units wherever possible in the thesis, although there may be some deviations where other conventions are the industry standard. Where appropriate I'll be using prefixes to avoid long and ugly numbers. LaTeX provides the excellent siunitx package for typesetting units which I will be using heavily. When used in tables and figures to apply to an axis, row or column I will be using a slash to denote the units. This is recommended by the BIPM as the correct method of expressing values for multiple quantities. It effectively divides the title by the units, making the values dimensionless.
However, going against the BIPM advice, I will be including a space before and after the slash, as I feel that this separates it from the axis title - which may be multiple words, and it reduces confusion between the slash and the units themselves. With the slash present all the denominator parts of the units will be referred to as a power of -1.

Scientific notation

Due to the mathematics of my work covering a large number of physical domains, including thermal, mechanical and electrical, I ended up with a relatively large notation section. I also began to run out of letters in the latin and greek alphabets. I therefore ended up using a cursive script to denote thermal parameters, allowing me to reuse some letters.

Figure design

As far as possible I followed the guidance of Tufte in presenting data in my thesis.

Punctuation

http://tex.stackexchange.com/questions/55246/how-to-properly-typeset-all-forms-of-punctuation-used-in-english-language-docume/55911#55911

Acronyms


Line spacing


Margins

This seems to be the subject of as much debate as anything else in typography and formatting! Things I think are worth considering: binding, screen reading, ease of reading, general prettiness. By default LaTeX gives you a larger margin on the outside when you request twosided document. This is to maintain the same distance between text in the centre as it does at the edge. It does not make any allowance for binding.

The "classicthesis" LaTeX style gives really quite a narrow column of text. This style emulates Bringhursts The Elements of Typographic Style, which seems to be regarded by many as the definitive guide to the subject. The classicthesis documentation has this to say:
"The size of the text body is intentionally shaped like it is. It supports both legibility and allows a reasonable amount of information to be on a page. And, no: the lines are not too short."

None of this addressed binding, which seems to be considered separately, however must be allowed for in thesis printing. University guidelines have this to say: "To allow for binding the margin at the binding edge of any page must be not less than 40mm; other margins must be not less than 15mm.".

A further consideration is the fact that the thesis will frequently be viewed in digital format. In this case margins are not necessarily required, and variation in margins between odd and even pages is likely to be distracting. This suggests that specific formatting for two sided printing should be avoided.

As a compromise I will be using equal margins either side of the text. When bound this will produce a narrower inside margin. I will also be placing page numbering at the centre of the page and titles always on the left, this should maintain uniform readability for screen reading. I will use 40mm for both margins, as this is the minimum allowed for the binding margin by the guidelines, this also achieves a 0.62 proportion, not far from the 2/3 often advocated.

The top and bottom margins are allowed to go as low as 15mm, and at this limit the document scrolls very nicely during screen reading. However, it looks unwieldy in printed form. Therefore I've opted for a 25mm margin at the top and a 35mm margin at the bottom, with page numbering placed in the centre of the bottom margin.

Punctuating equations

Punctuate as if they were part of the sentence.
or don't as it may confuse the reader?
Personally I agree with this answer, therefore I shall punctuate equations that are displayed inline, or where the sentence continues below the equation, but I won't use periods to end a sentence within a numbered equation; in this instance I shall try to use a colon prior to the equation.

Related: should notation be introduced in the text flow or in brackets? I introduce them without brackets.

Font

I ended up using LaTeX's default Times font rather than anything too fancy. This was easy and familiar to me and most readers.


Justification

Most technical articles tend to use fully justified text and there is some evidence that this is of benefit to dyslexics. One downside is the increased tendency for justified text to create distracting "rivers" of white space. One improvement is the use of microtypography techniques. These are pretty easy to use in LaTeX and there doesn't seem to be any downsides, so I'll be using them.

Tables and Figures

Tables and figures will appear throughout as soon a practically possible after they are referenced in the text. They will all be centred with a centred caption, Tables will have a caption above, Figures below. Captions will not be punctuated with a final period if they are only a sentence fragment, however they will be if they are a complete sentence or there are multiple sentences. Figures will not have a title above them, the caption below providing all the required information.


This is obviously a work in progress post... but if anyone has comments then I'd love to hear them!

No comments:

Post a Comment