rule_template_with_examples.yml

# This file provides an in-depth explanation of how YAML rulesets work. If you'd like a more bare-bones template that you can quickly copy/paste to create and edit rulesets, check out `rule_template_generic.yml`. 

description: Guidelines for using those familiar dots, dashes, and squiggles.
# Each ruleset file should only have one description. This description will be displayed on the page(s) where that ruleset is being displayed—for example, punctuation.yml corresponds to the /<audience>/punctuation pages.

content: 
# Each ruleset file should only have one 'content' key.
# Note that the content of these ruleset files will always be evaluated from top to bottom. As such, if you want your pages to include sections (or the rules in each section) arranged in a particular order, you'll need to order them accordingly in the YAML file itself. For example, I've chosen to arrange the `section` keys in this template file in alphabetical order to ensure that the corresponding pages' h2 headers will also be arranged in alphabetical order.

- section: Colons
# Most ruleset files have more than one 'section' key. This section name will automatically appear as an h2 header on the page where the ruleset file is displayed—do NOT add the `##` in the section value itself.
# Sections help group similar rules together; it's also possible to have a section with only one rule (like this one).

  sectionrules: 
  # Each section's rules should be contained within a single `sectionrules` key. This particular `sectionrules` key only contains a single rule because we only have one rule about colons, but if we had multiple rules about colons, all of them would still need to correspond to a single `sectionrules` key.

  - rule: |
      ### Colons and capitalization<br> 
      If you're using a colon within a self-contained sentence, the first word following the colon should remain lowercase (unless that word is a proper noun).
    # If you'd like to add a title to a rule, use h3 syntax (`###`) to include that title in the body of the rule itself, then use `<br>` to create a line break.
    # (You can also use `<br>` as you see fit to create line breaks within the body of the rule or any of its examples.)
    examples: 
      - |
        **Example:** We use three metrics in our analysis: quality, cost, and speed.
    # Each example will automatically be generated with a bullet point in front of it—do NOT add the bullet point in the body of the example itself (unless you're actually trying to create an example with a bulleted list in it, which is a different story). 
    # Rules can include one or multiple examples, or no examples at all. However, if a rule contains no examples, you can just omit the `examples` key entirely to keep things clean.
    audience: [tw, mktg] 
    # Possible audience values are `tw`, `dev`, and `mktg`. The order of these values doesn't matter as long as all relevant values are included within a single array.
    # You can add or delete audiences for each rule as needed. Editing a rule's audience values will automatically add/remove that rule to the audience page that draws upon a specified ruleset For example, this particular rule is currently configured to appear in `/tw/punctuation/` and `/dev/punctuation/`.

- section: Commas
  sectionrules:
  # This is a new section called "Commas" to group rules about commas.

  - rule: |
      ### Clauses<br>
      If two independent clauses are separated by a coordinating conjunction, use a comma unless both clauses are very short.
    examples:
      - |
        **Long:** We built everything slowly over the course of several months, and it all seems to work so far.
      - |
        **Short:** We worked too quickly and it all fell apart.
    audience: [tw, mktg]

  - rule: |
      If a dependent clause and an independent clause are separated by a coordinating conjunction, don't use a comma unless the sentence would be unclear without it.
    # Rules aren't required to have titles—this rule doesn't have a title at all. 
    # Since the content of the rule still falls under the "Clauses" grouping of the rule preceding it, I opted to omit an h3 header here to make the preceding rule and the current rule flow together. This kind of flow can be useful if you'd like to chain together multiple rule explanations with their own respective examples (as seen here).
    examples:
      - |
        **Clear without comma:** The vacuum of space is cold and will kill you almost instantly. 
      - |
        **Needs comma for clarity:** Vacuums are unforgiving in space, but clean carpets marvelously well.
    audience: [tw, mktg]

  - rule: |
      ### Introductory phrases<br>
      Use a comma after an introductory phrase (like *however* or *furthermore* or *on the other hand*).
    examples:
      - |
        **Example:** Despite this, we reached the mouth of the cave by sundown.
    audience: [tw, dev, mktg]

  - rule: |
      ### Serial commas<br>
      Use serial commas (also known as *Oxford commas*).
    examples:
      - |
        **No:** I love my parents, Godzilla and Wonder Woman.
      - |
        **Yes:** I love my parents, Godzilla, and Wonder Woman.
      # This rule has two examples.
    audience: [tw, dev, mktg]
    featured: |
      [Use serial commas.]({{site.baseurl}}{{page.permalink}}punctuation/#serial-commas)
    # If you'd like a rule to be featured on an audience's landing page, you can add the `featured` key to create a hyperlink from a short description. 
    # In this example, "{{site.baseurl}}" and "{{page.permalink}}" will automatically be replaced by the necessary values, but I've specified "punctuation" as the URL of the page(s) that this YAML ruleset corresponds to and "#serial-commas" as the header of rule in question. (This is one reason why it's handy to create h3 headers for rules!)

# The rest of this template is presented without additional comments. Everything included below follows the same principles as outlined above, but it may be helpful to see more rules in action without so many comments clogging up the YAML syntax. ;) 

- section: Dashes and hyphens
  sectionrules:

  - rule: |
      ### Em dashes<br>
      You can use em dashes—just don't put spaces between the em dash and the words surrounding it.
    audience: [tw, mktg]

  - rule: |
      ### Compound modifiers<br>
      Use a hyphen between compound modifiers unless the first word is in adverb ending in *-ly*. 
    examples:
      - |
        **Hyphenated:** well-learned students
      - |
        **Not hyphenated:** easily performed tasks
    audience: [tw, mktg]

  - rule: |
      ### Compound words<br>
      Sometimes it's helpful to hyphenate compound words to avoid ambiguity. A good rule of thumb is to use a hyphen for compound words that aren't widely used or that could be mistaken for another word.
    examples:
      - |
        **Hyphenated:** re-create, pre-date<br>
      - |
        **Not hyphenated:** remix, prepaid
    audience: [tw, mktg]

  - rule: |
      ### Prefixes<br>
      Use a hyphen between a prefix and a proper noun or abbreviation.
    examples:
      - |
        **Example:** Files with non-JSON syntax are unsupported.
    audience: [tw, mktg]

  - rule: |
      ### Suspended hyphens<br>
      Use suspended hyphens to list several hyphenated compounds in a row.
    examples:
      - |
        **Example:** The craft fair offers soap- and basket-making classes.
      - |
        **Example:** Bills come in one-, five, and twenty-dollar increments.
    audience: [tw, mktg]

- section: Parentheses
  sectionrules:

  - rule: |
      ### Avoid critical information<br>
      Some readers may skip over any text that isn't part of the main sentence, so try not to include any critical information inside parentheses.
    audience: [tw, dev]

  - rule: |
      ### End punctuation<br>
      Place end punctuation marks (like commas and periods) outside parentheses unless the punctuation is part of the parenthetical text or the parentheses contain a standalone sentence.
    examples:
      - |
        **Outside parentheses:** It's legal to own a zebra in certain states (like Nevada).
      - |
        **Inside parentheses:** It's legal to own a zebra in certain states. (Nevada is one of them.)
    audience: [tw, mktg]

  - rule: |
      ### Mid-sentence parentheticals<br>
      Parenthetical statements are useful for mid-sentence examples and short asides (like this one), but excessively long and complicated parentheticals may be better of rewritten as their own sentence (or else you'll end up with a meandering, monstrous behemoth of a sentence that seems to go on and on and on with no end in sight).
    audience: [tw, mktg]

- section: Semicolons
  sectionrules:

  - rule: |
      ### Avoid overuse<br>
      Semicolons are your friend; however, like any friend, you might get sick of them if they show up too frequently. Tread carefully and wisely.
    audience: [tw, dev, mktg]

  - rule: |
      ### Clauses<br>
      You can use a semicolon to connect two independent clauses.
    examples:
      - |
        **Example:** The film received terrible reviews; none of the reviewers could even stay awake through the whole thing.
    audience: [tw, mktg]

  - rule: |
      You can also use a semicolon to connect two independent clauses connected by a conjunctive adverb (like *however* or *similarly*) or, occasionally, a regular old conjunction (like *and* or *but* or *if*).
    examples:
      - |
        **Example:** Most mountains aren't as tall as Everest; however, they still pose a suitable challenge for climbers.
    audience: [tw, mktg]

  - rule: |
      But consider carefully whether you really need a semicolon or if you'd be better off breaking things into two separate sentences.
    audience: [tw, mktg]

  - rule: |
      ### Lists<br>
      When commas alone won't suffice, you can use semicolons to separate complex items in a series or list.
    examples:
      - |
        **Example:** Our team includes May, a prestigious researcher; Brendan, a tenacious explorer; and Wally, a skilled analyst.
    audience: [tw, dev, mktg]