path: root/doc/style-guide-for-documentation

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




‘an’ versus ‘a’
---------------
Follow the rule that says only words starting with
a vowel is preceded by ‘an’. This means that semivowels
and ‘h’:s regardless of silentness and even
syllable-emphasis are preceded by ‘a’.
For example:
  ‘a universe’     (phonetically starts with semivowel ‘j’)
  ‘a hyperbola’    (starts with non-silent ‘h’, emphasis on second syllable)
  ‘a hotel’        (starts with non-silent ‘h’ in modern pronunciations)
  ‘an hour’        (phonetically starts with diphthong ou, ‘h’ is silent)
  ‘an umbrella’    (starts with vowel ‘u’, no ‘j’ is prepended)
  ‘a hammer’       (starts with consonant ‘h’, no ‘j’ is prepended)
  ‘a July-night’   (starts with semivowel ‘j’, or alternatively consonant ‘dj’)
  ‘a ‘one’’        (phonetically starts with semivowel ‘w’)




Units
-----

Abstain from putting spaces between units and their multiplier. For example 1 metre,
should be written ‘1m’. This can help reduce ambiguity. For example,
“The computers in my house have 2 Gb/s ethernet-ports.” does not mean the same thing as
“The computers in my house have 2Gb/s ethernet-ports.” In fact, the first former means
“The computers in my house have 2 ethernet-ports with Gb/s capacity.” and the latter
means “The computers in my house have ethernet-ports with 2Gb/s capacity.”
This is however only important, if ambiguity is possible.