add style guide for documentation

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 174 insertions, 0 deletions

diff --git a/doc/style-guide-for-documentation b/doc/style-guide-for-documentation
new file mode 100644
index 0000000..f44a8bf
--- /dev/null
+++ b/doc/style-guide-for-documentation
@@ -0,0 +1,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’.
+