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
| Group | Element | Style | Example | Explanation |
|---|---|---|---|---|
| General | file name | italic | factory.ini | Paths for file names should start from an absolute directory that is usually specified by an environment variable, e.g. use $SCHEDULER_DATA/config/factory.ini instead of ./config/factory.ini. |
| environment variable | uppercase italic | $SCHEDULER_HOME | Environment variables are stated with a leading $ as used for Unix systems | |
| command line | italic | ./setup.sh | ||
| Parameters | parameter name | italic | command | |
| parameter value | monospace | select sysdate from dual | ||
| Code | any | monospace | var myNum = 25; | Code should be used with the Code Macro |
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.
Strikethroughis 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 sholuld 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 - particulary 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 part of a sentence is inserted into a
- 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 seperate 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)
- Use a comma to seperate items - e.g. "one, two, three and four"
- Do not use a comma before "and", "but" or "because"
- To structure a sentence:
- Writing in one word or multiple words
- German rules for writing in one word would not apply for English, therefore use "job chain" instead of "jobchain"