# Punctuation Style Rules

The following Style Rules pertain to punctuation:

Serial Commas
  Description: A serial comma (also known as the Oxford comma) is a comma that is placed immediately before coordinating conjunctions ("and", "or) in a series of three or more items. In other words, it is the comma that comes before the final item in the series. This is just a style rule and some writers choose to always include the serial comma, while others choose to never include it. The important thing is to always be consistent. However, omitting the serial comma can sometimes leads to ambiguity, especially in complex sentences, so it seems more logical to always include it rather than always omitting it.

  Rules: Always include a serial comma in a series of three or more items. Do not use a serial comma for just two items.

  Example: The following search actions can be applied on pattern, phase, or diagnostic types and are available from the Search submenu. [Notice that the serial comma is included before the third item in the series (before the "or" conjunction), but a comma is NOT included before "and" because the content after that conjunction is not part of the series of items ("pattern", "phase", "diagnostic types").

Punctuation at the end of Parentheses
  Description: There are usually two rules for using punctuation at the end of parentheses, depending on whether or not the content inside the parentheses is a complete sentence. However, in our documentation, content inside parentheses should never be a complete sentence, so our rules are quite simple.

  Rules: When ending punctuation is required after parentheses, always place it outside the parentheses. There might seem to be an exception to this when the last word in the parentheses is a contraction that requires a period (for example, etc.), but it actually still applies in that case because you would put the punctuation inside and outside the ending parenthesis.

Inside Quotations
  Description: There are two conflicting style rules in regards to whether punctuation goes inside or outside quotations, depending on whether you use American or British English rules. Since we use very few quotation marks in our documentation, it is unnecessary to go into extensive details about these rules. Instead, in those rare instances where quotations are used, we will use a simplified version of the American rules.

  Rules: In the rare instances where quotations are required, always place commas and periods inside the closing quotations mark, while semicolons, colons, and dashes always go outside the closing quotation mark. Avoid using other punctuation with quotations, or avoid using quotations.

Hyphens
  Description: There are a lot of complicated rules in regards to using hyphens and they depend on the type of word or words in question. Fortunately, there are really only two types of instances that we need to focus on for our documentation since all other possible instances would be very rare in our style of technical writing. In our case, the two types of words that require rules for hyphens are compound adjectives and prefixes.
  Rules for compound adjectives: Compound adjectives are two or more words that are combined to make an adjective and therefore describe a noun or noun phrase. Follow these rules in regards to hyphenating compound adjectives:
  - Always hyphenate compound words that include hyphens in their dictionary definitions. Examples: "right-click, "double-click", "built-in", "pop-up", "drop-down", "on-site".
  - Hyphenate compound adjectives whenever they are placed before a noun.
  - Do not hyphenate compound adjectives when they are placed after a noun, unless they are hyphenated by definition.
  - Do not hyphenate compounds that are formed with "ly" adverbs, even when they precede a noun they modify (for example, "fully developed program")
  - The most important thing is to avoid ambiguity, so if there is still a question as to whether or not to hyphenate the compound words, it is better to hyphenate them than the reverse.
  - DO NOT hyphenate the following words: "plugin", "screenshot", "checkbox"
  Rules for prefixes: When it comes to hyphenating prefixes, it is completely a style choice, but it is important to avoid ambiguity and it is preferable to hyphenate words that would otherwise look awkward. Based on that, in most cases, prefixes that result in two consecutive vowels should be hyphenated.
  - Examples of prefixes to hyphenate: "co-exist", "co-owner", "re-enable", "re-executing", "re-engineering", "re-evaluate", and ALL words that use the "non-" prefix.
Semi-Colons
  Rule: The only time that semi-colons should ever be used in the User Guide is in `codeblocks`.
Exclamation Marks
  Rule: Except for very rare instances, it is not necessary to use exclamation marks in the User Guide.