Style Guide

Page Styles

Table of Contents

• Each page starts with a table of contents should more than two headings be used in that page.

Headings

• At the top of a page the styles for Heading 1 or Heading 2 are used

• Headings are used in strict descending order
  • headings are not used for layout reasons but for better structure of the page content
  • Heading 3 follows Heading 2, not: Heading 4 follows Heading 2

Ordered and Unordered Lists

• Text should be grouped in unordered lists where applicable
• Such grouping is not intended for better layout but for a better structure of the presentation
• Try to group your thoughts accordingly, add hierarchies.

Element Styles

Markup

• Bold should not be used for markup except in headings, i.e. page headings, table headings etc.

• Understrike should not be used.
• _Subscript should not be used.
• ^Superscript is used exclusively for footnotes.
• Strikethrough is used to invalidate specific terms or sentences.
• Font colors are not used except for rare cases of error messages. A wiki article is targeted at structured content not at layout.

Character Styles

• Mixed uppercase and lowercase usage
  • Mixed spelling is used as for any English sentence
• Words in uppercase letters
  • Uppercase letters are used exclusively when technically required, e.g. for environment variables.
  • Uppercase letters should not be used for emphasis, e.g. do not use "WITHOUT WARRANTY".

Spelling & punctuation

• Use of dashes and hyphens
  
  • Hyphens are used less in English to join words than in German, so be careful when "importing" joined up words from German - particular words that were originally English.
  • Dashes are often used in English to link parts of a sentence:
    • they are often used where the writer is not sure whether a comma, colon or semi-colon should be used
    • they are used to add emphasis - like here - where a phrase is inserted into a sentence.
• Use of commas - these are very simplified rules!
  
  • To structure a sentence:
    • Commas are used less in English to structure sentences than in German, so if you are not sure whether a comma is required then don't use one.
    • Use a comma between parts of a sentence joined with a word starting with a "w" - such as "which", "who", "when"
      ("... enter the data in the search field, which you will find at the top right of the form.")
    • Don't use a comma between parts of a sentence joined with a word starting with a "t" - such as "that"
      ("... enter the data in the search field that you will find at the top right of the form.")
  • In lists of items:
    • Use a comma to separate items - e.g. "one, two, three and four"
      (but in lists of longer items - e.g. "this is item one; this is item two and this is item three" - use a semicolon and place a colon before the list)
  • Do not use a comma before "and", "but" or "because"
• Using joined-up words, separate words or words joined by a  hyphen:
  
  • German rules for writing in one word would not apply for English, therefore use "job chain" instead of "jobchain", even though this is often done, particularly in professional usage.
  • The most important general rule - that a hyphen should be used if both words used together have a different meaning to when they are used separately - is wonderfully ambiguous:
    • So, a hyphen is not required in "job chain" because a job chain is the same as a chain of jobs 
  • Hyphens are used to clear up meaning when this is clear from the text itself:
    • Example a: it is clear that "job chain parameter" would almost never refer to a "chain parameter" job so it is not necessary to use a hyphen between job and chain here.
    • Example b: "job-run time" and "job run-time" have different meanings.

    • Example c: "more-regular job starts" has a different meaning to "more regular job starts".