Start to clean up formatting

content-style-guide.md

@@ -1,7 +1,6 @@
-This is our company style guide. It helps us write clear and consistent content. Please use it as a reference when you’re writing for Agaric.  Adapted from <a href="https://styleguide.mailchimp.com/">Mailchimp</a> and available under a Creative Commons Attribution-NonCommercial 4.0 International license.
-
-This guide goes beyond basic grammar and style points. It’s not traditional in format or content. We break a number of grammar rules for clarity, practicality, or preference.
+# Agaric's Content Style Guide
 
+This is our company style guide. It helps us write clear and consistent content. Please use it as a reference when you’re writing for Agaric.  Adapted from [Mailchimp](https://styleguide.mailchimp.com/) and available under a Creative Commons Attribution-NonCommercial 4.0 International license.
 
 ## TL;DR
 
@@ -11,7 +10,7 @@ The Agaric Content Style Guide goes into depth on many subjects. It may be more
 
 Good content is:
 
-* Authentic, Useful and Appropriate
+* Authentic, Useful, and Appropriate
 
 ### Voice and tone
 
@@ -22,6 +21,7 @@ Agaric’s voice is:
 * Unconstrained but not incomprehensible
 * Open (curious, eclectic) but not scattered
 
+
 ### Writing about people
 
 We write and build apps with a person-first perspective. Being aware of the impact of your language is one way for us to live out our [values](values).
@@ -31,7 +31,9 @@ We write and build apps with a person-first perspective. Being aware of the impa
 * When writing about a person, use their preferred pronouns; if you don’t know those, just use their name.
 * Related resource: [The Conscious Style Guide](https://consciousstyleguide.com/).
 
+
 ### Grammar and mechanics
+
 Some people will read every word you write. Others will just scan. Help everyone by grouping related ideas together and using descriptive headers and subheaders.
 
 Focus your message, and create a hierarchy of information. Lead with the main point or the most important content.
@@ -43,11 +45,13 @@ Focus your message, and create a hierarchy of information. Lead with the main po
 * Avoid vague language.
 * Be consistent. Adhere to the copy patterns and style points outlined in this guide.
 * Feel free to use contractions.
-* Use the serial comma. Otherwise, use common sense.
+* Use the serial comma. Otherwise, use common sense. (Also known as the Oxford comma, it helps clarify when items in a list of three, four, or more things are their own items.)
 * Don’t use underline, and don’t use any combination of italic, bold, caps, and underline.
 * When in doubt, read your writing out loud.
 
+
 ### Writing for accessibility
+
 * Create a hierarchy, with the most important information first.
 Place similar topics in the same paragraph, and clearly separate different topics with headings.
 * Use plain language. Write short sentences and familiar words.
@@ -56,7 +60,9 @@ Place similar topics in the same paragraph, and clearly separate different topic
 * Avoid directional instructions or language that requires the reader to see the layout or design of the page.
 * Label inputs on forms with clear names and use appropriate tags. Think carefully about what fields are necessary, and especially which ones you mark as required.
 
+
 ### Writing for translation
+
 * Use active voice.
 * Avoid double negatives.
 * Use contractions with caution.
@@ -69,10 +75,12 @@ Place similar topics in the same paragraph, and clearly separate different topic
 ## Writing Goals and Principles
 
 With every piece of content we publish, we aim to:
+
 * **Empower**. Help people build the Open Web and the Free Software Movement by using language that informs them and encourages them to contribute.
 * **Inspire**. Lift up our work, our clients' work and our colleagues' work to inspire others to support them or pursue their own work.
 
 In order to achieve those goals, we make sure our content is:
+
 * **Authentic**. Write about what you are passionate about.
 * **Useful**. Before you start writing, ask yourself: What purpose does this serve? Who is going to read it? What do they need to know?
 * **Appropriate**. Write in a way that suits the situation. Just like you do in face-to-face conversations, adapt your tone depending on who you’re writing to and what you’re writing about.
@@ -105,13 +113,16 @@ Agaric’s tone is usually informal, but it’s always more important to be clea
 Agaric has a sense of humor, so feel free to be funny when it’s appropriate and when it comes naturally to you. If in any doubt, don't make the joke. Generally avoid humor in written communication to clients.
 
 ### Style tips
+
 Here are a few key elements of writing Agaric’s voice. For more, see the Grammar and mechanics section.
 
 **Active voice**
+
 * Use active voice. Avoid passive voice.
 * Avoid slang and jargon Write in plain English.
 
 **Write positively**
+
 * Use positive language rather than negative language.
 
 
@@ -120,39 +131,47 @@ Here are a few key elements of writing Agaric’s voice. For more, see the Gramm
 We write the same way we build software: with a person-first perspective. Whether you’re writing for an internal or external audience, it's important to write for and about other people in a way that’s compassionate, inclusive, and respectful. Being aware of the impact of your language will help make Agaric a better place to work and a better steward of our values in the world. In this section we'll lay out some guidelines for writing about people with compassion, and share some resources for further learning.
 
 ### Age
+
 Don’t reference a person’s age unless it’s relevant to what you’re writing. If it is relevant, include the person’s specific age, offset by commas.
 The CEO, 16, just got her driver’s license.
 Don’t refer to people using age-related descriptors like “young,” “old,” or “elderly.”
 
 ### Disability
+
 Don’t refer to a person’s disability unless it’s relevant to what you’re writing. If you need to mention it, use language that emphasizes the person first: ”she has a disability” rather than “she is disabled.”  When writing about a person with disabilities, don’t use the words “suffer,” “victim,” or “handicapped.” “Handicapped parking” is OK.
 
 ### Gender and sexuality
+
 Don’t call groups of people “guys.” Don’t call women “girls.”
 Avoid gendered terms in favor of neutral alternatives, like “server” instead of “waitress” and “businessperson” instead of “businessman.”
 It’s OK to use “they” as a singular pronoun.
 
 Use the following words as modifiers, but never as nouns:
-lesbian
-gay
-bisexual
-transgender (never "transgendered")
-trans
-queer
-LGBT
+
+* lesbian
+* gay
+* bisexual
+* transgender (never "transgendered")
+* trans
+* queer
+* LGBT
+
 Don’t use these words in reference to LGBT people or communities:
-homosexual
-lifestyle
-preference
+
+* homosexual
+* lifestyle
+* preference
 
 Don’t use “same-sex” marriage, unless the distinction is relevant to what you’re writing. (Avoid “gay marriage.”) Otherwise, it’s just “marriage.”
 
 When writing about a person, use their communicated pronouns. When in doubt, just ask or use their name.
 
 ### Hearing
+
 Use “deaf” as an adjective to describe a person with significant hearing loss. You can also use “partially deaf” or “hard of hearing.”
 
 ### Medical conditions
+
 Don’t refer to a person’s medical condition unless it’s relevant to what you’re writing.
 If a reference to a person’s medical condition is warranted, use the same rules as writing about people with physical disabilities and emphasize the person first. Don’t call a person with a medical condition a “victim.”
 
@@ -165,38 +184,54 @@ Use the adjective “blind” to describe a person who is unable to see. Use “
 
 
 ## Grammar and Mechanics
+
 Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent. This section will lay out our house style, which applies to all of our content unless otherwise noted in this guide. (We cover a lot of ground in this section—the search feature will help if you're looking for something in particular.)
 
+
 ### Basics
+
 Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.
 
 Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.
 
 Be concise. Use short words and sentences. Avoid unnecessary modifiers.
+
 Be specific. Avoid vague language. Cut the fluff.
+
 Be consistent. Stick to the copy patterns and style points outlined in this guide.
 
 ### Guidelines
 
 #### Abbreviations and acronyms
+
 If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.
+
 First use: Network Operations Center  
 Second use: NOC
+
 First use: Coordinated Universal Time (UTC)  
 Second use: UTC
-If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).
+
+If the abbreviation or acronym is well known to your full intended audience, like API or HTML in technical documentation, use it instead (and don’t worry about spelling it out).
+
 
 #### Active voice
+
 Use active voice. Avoid passive voice.
 
 In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
+
 Yes: Marti logged into the account.  
 No: The account was logged into by Marti.
+
 Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.
+
 One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.
-Your account was flagged by our abuse team.
+
+> Your account was flagged by our abuse team.
 
 #### Capitalization
+
 We use a few different forms of capitalization. Title case capitalizes the first letter of every word except articles, prepositions, and conjunctions. We use title case for the titles of pages, including blog posts and basic pages.
 
 Sentence case capitalizes the first letter of the first word.
@@ -400,18 +435,23 @@ Capitalize the names of websites and web publications. Don’t italicize.
 Avoid spelling out URLs, but when you need to, leave off the http://www.  
 
 ## Writing about Agaric  
+
 Our company's legal entity name is "Agaric, LLC." Our trade name is "Agaric." Use "Agaric, LLC" only when writing legal documents or contracts. Otherwise, use "Agaric."
-Always capitalize “Agaric.”  
+
+Always capitalize Agaric.  
+
 Refer to Agaric as “we,” not “it.”  
+
 Capitalize the proper names of Agaric products, features, pages, and tools.   
 
-**Writing about other companies**
-Honor companies’ own names for themselves and their products. Go by what’s used on their official website. Unless they end with a ‘!’ that’s just absurd and will not be respected!
-iPad  
-YouTube  
+## Writing about other companies
+
+Honor companies’ own names for themselves and their products. Go by what’s used on their official website. Unless they end with an exclamation point ('!'); that's absurd and will not be respected!
+
 Refer to a company or product as “it” (not “they”).  
 
 **Slang and jargon**
+
 Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.
 
 Agaric’s ops team is constantly scaling our servers to make sure our users have a great experience with our products. One way we do this is with shards, or partitions, that help us better horizontally scale our database infrastructure.