aboutsummaryrefslogtreecommitdiffstats
path: root/doc/style-guide-for-documentation
blob: ff65d2ec7fe2e7a6dc1dbd1e164d428523c6fb4a (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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
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. Note well, it is hypercorrect (incorrect) to
replace a space with a hyphen to emphasis linking between
words to avoid ambiguity.
Some examples:
  Correct: Pro-Russian forces
    ‘Pro-’ is prefix and ‘Russian’ as capitalisation on its
    first letter, requiring a hyphen.

  Incorrect: I am pro-GPL
  Correct: I am pro GPL
    ‘Pro’ is not a prefix this case, but rather a preposition,
    you have an opinion rather than being an object.

  Incorrect: Linux powered computer
  Correct: Linux-powered computer
  Incorrect: Linuxpowered computer
    In the first example, powered with past tense of the verb
    power. Note, it is almost grammatically correct, but it does
    not mean what was intended, the only grammatical error is that
    ‘computer’ needs to be replace by ‘a computer’, ‘computers’ or
    ‘the computer’. In the second and third example the tense is
    present, but the computers are powered by Linux rather than that
    Linux used to power the computer. The third example is however
    incorrect because Linux is a proper noun.

  Incorrect: Solar powered computer
  Correct: Solar-powered computer
  Preferred: Solarpowered computer
    Similar to the previous group of examples.
    ‘Solar’ is not a noun (in this case), but an adjective, so the
    first example is incorrect. ‘Solar’ and ‘powered’ needs to be
    joined to form a single, four-morpheme (both ‘solar’ and ‘powered’
    are two-morpheme), word. This can either be done with a hyphen
    or by a complete join without space or hyphen, the latter is
    preferred.

  Correct: A solar day on Mars
  Incorrect: A solar-day on Mars
    ‘Solar’ is an adjective. Adjectives and nouns are never joined.




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, or multiple family, however dual-plural form
is not allowed in this case.




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

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