aboutsummaryrefslogtreecommitdiffstats
path: root/doc/style-guide-for-documentation
blob: f44a8bfe88fcb068c18ce69382d21e8a08970d98 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
Follow the English Style Guide from European Commission
Directorate-General for Translation, except where it
conflicts with these guides below.



American or British spelling?
-----------------------------

Use British spelling. And when choosing between words,
choose the ones that are more common in British English
than in American English rather than the ones that are
more common in American English than in British English.




Use of ash
----------

Ash (æ) should always be used when it can be used properly.
That is, when it is not a loanword that did not use it in
the original language, and when there is a A–E-diphthong.
For example ‘formulæ’ rather than ‘formulae’.




Use of diæresis
---------------

Diæresis (¨) should be used (on the second letter) when
there is a hiatus rather than a diphtong, or a hiatus
rather than a vowel sound spelled with two vowels.
Diæresis should however not be used between roots and
affixes.
For example ‘coordinate’ rather than ‘coördinate’, but
‘naïve’ rather than ‘naive’.




Use of hyphen
-------------

Hyphens is preferred over space, but use of neither hyphen
nor space is preferred over use hyphen. Abstence of hyphen
is especially preferred between roots and affixes.
For example ‘coordinate’ rather than ‘co-ordinate’ and
‘filesystem’ rather than ‘file-system’ or ‘file system’,
but ‘e-mail’ rather than ‘email’ (see next section; the ‘e’
is an abbrevation).
Hyphen should however be used if it significantly improves
readability.




Inflection of abbreviations, contractions, acronyms and loanwords
-----------------------------------------------------------------

Assume ‘X’ is an abbreviation, contractions, acronym or loanword.

Plural form:                           X:s or X:es
Singular possessive case:              X's
Plural possessive case:                X:s' or X:es'
Past tense form:                       X:d or X:ed
Gerundisation and similar inflection:  X:ing and similar
As one of the morphemes in a word:     Y-X, X-Z or Y-X-Z,
  where Y and Z are morphemes that may or may not be
  abbreviations, acronyms or loanwords.




Use of periods in abbreviations, contractions and acronyms
----------------------------------------------------------

Never, except the the end of the words in abbreviations.
For example ‘Mr’ rather than ‘Mr.’ and not ‘NATO’ rather than
‘N.A.T.O.’, but ‘abbr.’ rather than ‘abbr’.




Use of colon in contractions
----------------------------

Avoid.




Use of abbreviations and contractions
-------------------------------------

Avoid at all cost, except the few uncontroversial abbreviations
and contractions: ‘Mr’, ‘Mrs’ and ‘Dr’. (‘Mrs’ is not a true
contraction), ‘CD’, ‘USB’ and ‘DVD’. (‘DVD’ is not an abbreviation
or acronym, it is just three random letters that does not stand for
anything.) These are the only abbreviations and contractions you
can use uncontroversially. This is however in when use the
contractions as a title before a name. For example you may write
‘Dr Joe Random’, but not ‘today I saw a dr’.

‘a.m.’ and ‘p.m.’ would be allowed, however, they are not used, as
time should be expressed in HH:MM- and HH:MM:SS-24-hour time-format.

‘&’ (a ligature as an abbreviation) should be avoided, and is
only allowed in titles and in verbatim sections.

‘§’ and ‘§§’ (ligatures as abbreviations) is allowed in and only in
verbatim sections and when referring a section or numbering a section.




Acronyms as generic words
-------------------------

Unacceptable, always use captialised form.
For example ‘LASER’ rather than ‘laser’.




-ize versus -ise
----------------

Always -ise, no exceptions. All words that can be
spelled with -ize can also be spelled with -ise,
the reverse however is not true.
For example ‘randomise’ rather than ‘randomize’.




Use of serial comma
-------------------

Only use serial comma when necessary.




Possessive form of classical and biblical names
-----------------------------------------------

Adhere to the standard for non-classical, non-biblical
names. For example ‘Socrates's philosophy’ rather than
‘Socrates' philosophy’.




Plural of proper nouns
----------------------

Proper nouns cannot be declenated to plural form with
indefinite state or construct state. For example ‘there
are two Richard in this room’ rather than ‘there are two
Richards in this room’, and ‘both Richard.’ rather than
‘both Richards’. However proper nouns can be declenated
to plural form with definite state, but only when referring
to a family.




Can't versus cannot
-------------------

Use ‘cannot’ rather than ‘can't’.