diff options
| -rw-r--r-- | doc/style-guide-for-documentation | 174 |
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’. + |