aboutsummaryrefslogtreecommitdiffstats
path: root/doc/style-guide-for-documentation
blob: 65f1aa6eee4804ff1dc38b1747e9af204c3cd767 (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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
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.

  Incorrect: A speech-to-text technology
  More incorrect: A speech to text-technology
  Most incorrect: A speech to text technology
  Most incorrect: A speechtotexttechnology
  Correct: A speech-to-text-technology
  Incorrect: A speech-to-texttechnology
    ‘speech-to-text’ is a noun, hence one word. ‘technology’ is also
    a noun. The two nouns must be joined because they form a single
    noun. However, because ‘speech-to-text’ is a phrase where the words
    are joined by hyphens (they most be joined by hyphens because it is
    a phrase,) ‘speech-to-text’ and ‘technology’ most be joined with a
    hyphen, however, using a space in a case like this is tolerable.

  Verb: Log in; back up
  Noun: Log-in; back-up
  Preferred noun: Login; backup
    The preposition is a part of the lexeme. The noun and the proposition
    are joined to form a new noun. However, this is not done on verbs.
    Is probably has to do with how the lexemes are inflected.




Full form versus contracted form
--------------------------------

Contractions are not acceptable, except, for ‘-n't’, for example
‘don't’ and ‘won't’. Additionally, ‘o'clock’ is allowed because
it is considered mandatory in contemporary use, consequentially
‘of the clock’ must not be written.
Contractions are especially intolerable when it is ambiguous by
itself even if the full sentence makes it unambiguous. Therefore
‘-'s’ and ‘-'d’ most never be used.




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’. This is especially important for acronyms that are not
pronounceable exactly. For example ‘radar’ is tolerable, but ‘tv’ is
intolerable.




-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’.




Genderneutral form
------------------

Genderneutral form is identical to feminine form.
For example, write ‘The user … if she …’ rather than:
  ‘The user … if he …’
  ‘The user … if she/he …’
  ‘The user … if he/she …’
  ‘The user … if s/he …’
  ‘The user … if the user …’
  ‘The user … if it …’
  ‘The user … if one …’
  ‘One … if one …’
  ‘… if you …’