Greatly improve formatting

content-style-guide.md

@@ -359,93 +359,135 @@ the 1890s
 
 #### Punctuation
 
-**Apostrophes**
+##### Apostrophes
-The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ‘s. If the word ends in an s and is plural, just add an apostrophe.  
+
+The apostrophe's most common use is making a word possessive. If the word already ends in an s and it is singular, you also add an 's. If the word ends in an s and is plural, just add an apostrophe.  
 The doughnut thief ate Sam’s doughnut.  
 The doughnut thief ate Chris’s doughnut.  
 The doughnut thief ate the managers’ doughnuts.  
-Apostrophes can also be used to denote that you’ve dropped some letters from a word, usually to match spoken language— an unofficial contraction*. This is fine, but do it sparingly.  
 
-**Colons**
+Apostrophes can also be used to denote that you have dropped some letters from a word, usually to match spoken language— an unofficial contraction. This is fine when quoting or paraphrasing and giving the feel of a statement is important, but do it sparingly.  
+
+
+##### Colons
+
 Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.  
 Erin ordered three kinds of doughnuts: glazed, chocolate, and pumpkin.  
 You can also use a colon to join 2 related phrases. If a complete sentence follows the colon, capitalize the 1st word.  
 I was faced with a dilemma: I wanted a doughnut, but I’d just eaten a bagel.  
 
-**Commas**
+##### Commas
-When writing a list, use the serial comma (also known as the Oxford comma).
  
+
+When writing a list, use the serial comma (also known as the Oxford comma).
+
 Yes: David admires his parents, Oprah, and Justin Timberlake.  
 No: David admires his parents, Oprah and Justin Timberlake.  
-Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.  
 
-**Dashes and hyphens**
+Otherwise, use common sense. If you are unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.  
-Use a hyphen (-) without spaces on either side to link words into single phrase.  
+
-first-time user  
+##### Dashes and hyphens
+
+Use a hyphen (-) without spaces on either side to link words into single phrase
+
+  * first-time user
+
 To indicate a span or range, use an n-dash (–).
-Monday–Friday  
+
+  * Monday–Friday
+
 Use an em dash (—) with a space after the dash to offset an aside.  Use a true em dash, not hyphens (- or --).
-Multivariate testing—just one of our new Pro features— can help you grow your business.  
-Austin thought Brad was the donut thief, but he was wrong— it was Lain.  
 
-**Ellipses**
+  * Multivariate testing—just one of our new Pro features— can help you grow your business.
-Ellipses (...) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.
+  * Austin thought Brad was the doughnut thief, but he was wrong— it was Lain.  
-“Where did all those doughnuts go?” Christy asked. Lain said, “I do not know...”  
+
+
+##### Ellipses
+
+Ellipses (…) can be used to indicate that you are trailing off before the end of a thought. Use them sparingly. Do not use them for emphasis or drama, and do not use them in titles or headers.
+
+  * "Where did all those doughnuts go?" Christy asked. Lain said, "I do not know…"
+
 Ellipses, in brackets, can also be used to show that you are omitting words in a quote.
-“When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, [...] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”
 
-**Periods**
+  * “When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, […] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”
+
+##### Periods
+
 Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
-Christy said, “I ate a doughnut.”  
-I ate a doughnut (and I ate a bagel, too).  
-I ate a doughnut and a bagel. (The doughnut was Sam’s.)  
-Leave a single space between sentences. Unless using a period ligature that provides more space at the end of a sentence than in acronyms, this can be ambiguous: We went to the U.S. I told him.
 
-**Question marks**
+  * Christy said, "I ate a doughnut."
+  * I ate a doughnut (and I ate a bagel, too).
+  * I ate a doughnut and a bagel. (The doughnut was Sam's.)
+
+Use two spaces after a period between sentences.  This will be ignored in HTML but gives the opportunity to begin using a ligature that provides slightly more space at the end of a sentence than in acronyms, to prevent ambigities in interpretation such as:  "We went to the U.S. I told him."
+
+##### Question marks
+
 Question marks go inside quotation marks if they’re part of the quote. Like periods, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
 
-**Exclamation points**
+##### Exclamation points
+
 Use exclamation points sparingly, and never more than one at a time.
+
 Exclamation points go inside quotation marks.  Like periods and question marks, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
+
 Never use exclamation points in failure messages or alerts. When in doubt, avoid!
 
-**Quotation marks**
+##### Quotation marks
+
 Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.
+
 Periods and commas go within quotation marks. Question marks within quotes follow logic— if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.
+
 Use single quotation marks for quotes within quotes.
-Who was it that said, “A fool and his doughnut are easily parted”?  
-Brad said, “A wise man once told me, ‘A fool and his doughnut are easily parted.’”  
 
-**Semicolons**
+  * Who was it that said, “A fool and his doughnut are easily parted”?
-Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.
+  * Brad said, “A wise man once told me, ‘A fool and his doughnut are easily parted.’”  
+
+##### Semicolons
+
+Go easy on semicolons; they usually support long, complicated sentences that could be simplified. Try an em dash (—) instead, or simply start a new sentence.
+
+##### Ampersands
 
-**Ampersands**
 Do not use ampersands unless one is part of a company or brand name.  
-Ben and Dan  
-Ben & Jerry’s  
-People, Places, and Things  
 
-**File extensions**
+  * Ben and Dan
+  * Ben & Jerry’s
+  * People, places, and things
+
+##### File extensions
+
 When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.
-GIF  
+
-PDF  
+  * GIF
-HTML  
+  * PDF
-JPGs  
+  * HTML
+  * JPGs
+
 When referring to a specific file, the filename should be lowercase:
-slowclap.gif  
-MCBenefits.pdf  
-ben-twitter-profile.jpg  
-ilovedonuts.html  
 
-**Pronouns**
+  * slowclap.gif
+  * agaric-example-org-website-proposal.pdf
+  * ben-twitter-profile.jpg
+
+##### Pronouns
+
 If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun.  
-For more on writing about gender, see Writing about people.  
 
-**Quotes**
+```{seealso}
+For more on writing about gender, see Writing about people.  
+```
+
+##### Quotations
+
 When quoting someone in a blog post or other publication, use the past tense.  
 “Working with Agaric has helped our business grow,” said Jamie Smith.  
 
-**Names and titles**
+##### Names and titles
+
 The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.
+
 Capitalize the names of departments and teams (but not the word "team" or "department").  
 Marketing team  
 Support department  
@@ -507,23 +549,28 @@ No: You can’t get a donut if you don’t stand in line.
 
 
 ## Content Types
+
 Content at Agaric takes many forms. Here’s a rundown of the types of content we most often write, the functions they serve, and the teams that handle them.  
 
 ### Short
 
-#### Error or failure message
-What: Short message that alerts the user to a problem in their account or on their site 
-Length: 20-75 words  
-Owner: Developer  
-Example: Looks like you may have left our default header content unmodified. Specifically, we still see ‘Use this area to offer a short preview’ in the pre-header/header area.  
-
 #### Interface copy  
 
 What: Explanatory messaging that guides and informs users  
 Length: 10-50 words  
-Owner: Developer  
 Example: To get started, set a URL to import.  
 
+##### Success message
+What: Short, encouraging message letting the user know they’ve accomplished something in the app  
+Length: 5-20 words  
+Example: Excellent! Your account has been created 
+
+##### Error or failure message
+What: Short message that alerts the user to a problem in their account or on their site 
+Length: 20-75 words  
+Example: Looks like you may have left our default header content unmodified. Specifically, we still see ‘Use this area to offer a short preview’ in the pre-header/header area.  
+
+
 #### Social media
 
 What: Posts on Twitter, Facebook, Instagram, and LinkedIn that highlight blog posts, events, notable Agaric clients, and more  
@@ -535,12 +582,6 @@ Example: The City of Camrbidge uses Agaric's Find It platform to make it easier
 [Writing for social media](#writing-for-social-media)
 ```
 
-#### Success messag
-What: Short, encouraging message letting the user know they’ve accomplished something in the app  
-Length: 5-20 words  
-Owner: Product  
-Example: Excellent! Your account has been created 
-
 ### Long
 
 #### Blog post  
@@ -560,7 +601,7 @@ Length: 200-1000 words
 Example: Agaric needs to finally start one!
 
 ```{seealso}
-[Writing email newsletters](#writing-email-newsletters)
+[Writing newsletters](#writing-newsletters)
 ```
 
 #### How To article