Update content-style-guide.md

content-style-guide.md

@@ -144,11 +144,12 @@ Don’t refer to people using age-related descriptors like “young,” “old,
 
 ### Ability
 
-Don’t refer to a person’s ability 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.
+Don’t refer to a person’s ability 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. Avoid using ableist language whenever possible.
 
 ### Gender and sexuality
 
-Don’t call groups of people “guys.” Don’t call women “girls.”
+Don’t call groups of people “guys.” "Y'all" is a useful, non-gendered term for addressing groups of people.
+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.
 
@@ -162,15 +163,15 @@ Use the following words as modifiers, but never as nouns:
 * queer
 * LGBT
 
-Don’t use these words in reference to LGBT people or communities:
+Don’t use these words in reference to LGBTQIA people or communities:
 
 * 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.”
+Don’t use “same-sex” marriage, unless the distinction is relevant to what you’re writing. Avoid using “gay marriage," instead use “marriage.”
 
-When writing about a person, use their communicated pronouns. When in doubt, just ask or use their name.
+When writing about a person, use their communicated pronouns. When in doubt, just ask for their pronouns or use their name.
 
 ### Hearing
 
@@ -179,17 +180,17 @@ Use “deaf” as an adjective to describe a person with significant hearing los
 ### 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.”
+If a reference to a person’s medical condition is warranted, emphasize the person first. Don’t call a person with a medical condition a “victim.” Instead, use "patient.""
 
 ### Mental and cognitive conditions
 Don’t refer to a person’s mental or cognitive condition unless it’s relevant to what you’re writing. Never assume that someone has a medical, mental, or cognitive condition.
-Don’t describe a person as “mentally ill.” If a reference to a person’s mental or cognitive condition is warranted, use the same rules as writing about people with physical disabilities or medical conditions and emphasize the person first.
+Don’t describe a person as “mentally ill.” If a reference to a person’s mental or cognitive condition is warranted, use the same rules as writing about abilities or medical conditions and emphasize the person first.
 
 ### Vision
 Use the adjective “blind” to describe a person who is unable to see. Use “low vision” to describe a person with limited vision.
 
 
-## Grammar and Mechanics
+## 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.)
 
@@ -259,9 +260,9 @@ Emoji are a fun way to add humor and visual interest to your writing, but use th
 
 #### Numbers
 Spell out a number when it begins a sentence or is under ten. Ten to twenty is a judgement call (but usually spelled out if not paired with numerals). Otherwise, use the numeral. This includes ordinals, too.  
-Ten new employees started on Monday, and 12 start next week.  
-I ate 3 donuts at Coffee Hour.  
-Meg won 1st place in last year’s Walktober contest.  
+Ten new members started on Monday, and 12 start next week.  
+I ate 3 doughnuts at coffee hour.  
+Meg won 1st place in last year’s hackathon.  
 We hosted a group of 8th graders who are learning to code.  
 (Sometimes it feels weird to use "1" instead of "one." Just go with your gut.)  
 Numbers over 3 digits get commas:  
@@ -313,7 +314,7 @@ Use numerals and am or pm, with a space in between. Don’t use minutes for on-t
 Use an en-dash (–) between times to indicate a time period.
  
 7am–10:30pm  
 
-Specify time zones when writing about an event or something else people would need to schedule. Since MailChimp is in Atlanta, we default to ET.  
+Specify time zones when writing about an event or something else people would need to schedule. Since Agaric was founded and has several worker-owners in Boston, Massachusetts, we default to ET.  
 Abbreviate time zones within the continental United States as follows:  
 Eastern time: ET  
 Central time: CT  
@@ -327,7 +328,7 @@ the 00s
 the 90s  
 
 When referring to decades more than 100 years ago, be more specific:  
-the 1900s  
+the 1650s  
 the 1890s  
 
 #### Punctuation
@@ -485,41 +486,28 @@ Content at Agaric takes many forms. Here’s a rundown of the types of content w
 ### Short
 
 #### Error or failure message
-What: Short message that alerts the user to a problem in their account or campaign  
+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've 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 in-app messaging that guides and informs users  
+What: Explanatory messaging that guides and informs users  
 Length: 10-50 words  
 Owner: Developer  
 Example: To get started, set a URL to import.  
 Social media  
-What: Posts on Twitter, Facebook, Instagram, and LinkedIn that highlight blog posts, events, notable MailChimp users, and more  
+What: Posts on Twitter, Facebook, Instagram, and LinkedIn that highlight blog posts, events, notable Agaric clients, and more  
 Length: 20-30 words  
 Owner: Marketing, support  
-Example: Wilco used MailChimp's automation tools to release their new album. Here's how: http://blog.mailchimp.com/how-wilco-used-mailchimp-automation-to-release-its-new-album/
+Example: The City of Camrbidge used Agaric's FindIt platform to make it easier for people to find activities, events, and resources. Here's how: https://agaric.coop/work/find-it-cambridge
 See also: Writing for social media  
 
 #### Success message  
 What: Short, encouraging message letting the user know they’ve accomplished something in the app  
 Length: 5-20 words  
 Owner: Product  
-Example: Excellent! You have a brand new list.  
-
-### Medium
-
-#### Job listing
-What: Short description of company, role, and candidate qualifications  
-Length: 75-100 words  
-Owner: Recruiting  
-Example: Budget Manager  
-Marketing website copy  
-What: Messaging that markets our services and products to users and potential users  
-Length: 10-1,000 words  
-Owner: Marketing
-Example: Join more than 8 million people who use MailChimp to design and send 600 million emails every day.  
+Example: Excellent! Your account has been created 
 
 ### Long
 
@@ -541,7 +529,8 @@ Length: 300-1,000 words
 Owner: Knowledge Base  
 Example: Getting Started with Lists  
 See also: Writing technical content  
-Legal content  
+
+#### Legal content  
 What: Policies that explain how we protect user privacy and how we handle accounts  
 Length: 1,000-4,000 words  
 Owner: Legal
@@ -552,7 +541,7 @@ See also: Writing legal content
 What: Quick, informative announcements that we send to our media list and post to our Press Releases page.  
 Length: 300-500 words  
 Owner: Marketing  
-Example: MailChimp Hits Milestone 10 Billion Emails Per Month; Adding Headcount and Office Space  
+Example: Agaric Launches Data Visualization Platform for Healthcare Providers 
 
 
 ## Web Elements
@@ -739,7 +728,7 @@ We edit technical content based on three goals:
   * Use the simplest word.  
   * Limit paragraphs to three sentences.  
 * Consistency  
-  * Use the labels and terminology used in the MailChimp app.  
+  * Use the labels and terminology used in the Agaric client's app.  
   * Use specific, active verbs for certain tasks.  
   * Choose basic words and phrases to facilitate consistency across translated content.  
 * Helpfulness  
@@ -752,11 +741,11 @@ We edit technical content based on three goals:
 Technical content uses organization, capitalization, and other formatting to help convey meaning. Although different articles are organized differently, some formatting tips are consistent throughout all technical content.
 
 **Capitalization**
-Capitalize proper names of MailChimp products, features, pages, tools, and team names when directly mentioned. In step-by-step instructions, capitalize and italicize navigation and button labels as they appear in the app.  
-MailChimp, Mandrill  
-Campaigns page, Lists page  
-Compliance Team, Billing Team  
-Navigate to the Automation page.  
+Capitalize proper names of Agaric products, features, pages, tools, and team names when directly mentioned. In step-by-step instructions, capitalize and italicize navigation and button labels as they appear in the app.  
+FindIt  
+Menu page, Settings page  
+Training Team, Coding Team  
+Navigate to the Modules page.  
 Click Save & Close.  
 
 **Headings**
@@ -800,15 +789,16 @@ To write short, simplify your ideas or reduce the amount of information you’re
 Do your best to adhere to Agaric style guidelines when you’re using our social media channels to correspond with users. Use correct grammar and punctuation—and avoid excessive exclamation points.
 
 When appropriate, you can tag the subject of your post on Twitter or Facebook. But avoid directly tweeting at or otherwise publicly tagging a post subject with messages like, “Hey, we wrote about you!” Never ask for retweets, likes, or favorites.
-Yes: “We talked with @lauraolin about turning her awesome emails into a book. http://blog.mailchimp.com/how-laura-olins-emails-got-her-freelance-work-and-a-book-deal”
-No: “Hey @lauraolin, can you RT this post we wrote about you? http://blog.mailchimp.com/how-laura-olins-emails-got-her-freelance-work-and-a-book-deal”
+Yes: “We talked with @dinarcon about configuring YAML definition files https://agaric.coop/blog/drupal-migrations-reference-list-configuration-options-yaml-definition-files”
+No: “Hey @mlncn, can you RT this post we wrote about the training you're giving? https://agaric.coop/blog/learn-how-migrate-drupal-8-successfully-nonprofit-technology-pre-conference-day”
 
 ### Hashtags
 We employ hashtags rarely and deliberately. We may use them to promote an event or connect with users at a conference. Do not use current event or trending hashtags to promote Agaric unless it applies directly to our work (eg: #drupal #freesoftware #netneutrality).
 
 ### Trending topics
 * Do not use social media to comment on trending topics or current events that are unrelated to Agaric.  
-* Be aware of what’s going on in the news when you're publishing social content for Agaric.   * During major breaking news events, we turn off all promoted and scheduled social posts.  
+* Be aware of what’s going on in the news when you're publishing social content for Agaric.
+* During major breaking news events, we turn off all promoted and scheduled social posts.  
 
 ### Writing for Accessibility
 We’re always working to make our content more accessible and usable to the widest possible audience. Writing for accessibility goes way beyond making everything on the page available as text. It also affects the way you organize content and guide readers through a page. Depending on the audience and country, there may be laws governing the level of accessibility required. At minimum, an accessible version should be available. Accessibility includes users of all mental and physical capacities, whether situational (broken glasses!) or more permanent.
@@ -831,6 +821,9 @@ Many of the best practices for writing for accessibility echo those for writing
 Yes: “Select from these options,” (with the steps listed after the title)  
 No: “Select from the options in the right sidebar.”  
 
+### Use a skip navigation link
+Use a skip navigation link so that screen reader or keyboard-only users can avoid listening to or tabbing through many navigation elements before getting to the main content.
+
 ### Use headers
 Headers should always be nested and consecutive. Never skip a header level for styling reasons. To help group sections, be sure the page title is H1, top-level sections are H2s, and subsequent inside those are H3 and beyond. Avoid excessive nesting.
 
@@ -900,44 +893,43 @@ Keep your copy brief, but don’t sacrifice clarity for brevity. You may need to
 Yes: Customers who have ordered online can pick up their food at the cashier. Walk-in customers should stop by the cashier to order their food.  
 No: Customers who have ordered online or who are walk-ins should stop at the cashier to order or pick up their food.  
 Repeat helping verbs belonging to multiple verbs  
-Yes: MailChimp can send your campaign on the fly or can schedule your campaign to go out at a set time.  
-No: MailChimp can send your campaign on the fly or schedule your campaign to go out at a set time.  
+Yes: Agaric can build your website or can train your development team to build more powerful websites.
+No: Agaric can build your website or train your development team to build more powerful websites. 
 
 #### Repeat subjects and verbs
-Yes: Mandrill sends transactional emails, but MailChimp does not.  
-No: Mandrill sends transactional emails, but not MailChimp.  
+Yes: Most Agarics use contractions, but Micky does not. 
+No: Most Agarics use contractions, but not Micky.  
 
 #### Repeat markers in a list or series
-Yes: Use MailChimp to send email campaigns, to manage your mailing lists, and to integrate with other applications.  
-No: Use MailChimp to send email campaigns, manage your mailing lists, and integrate with other applications.  
+Yes: Use Agaric's FindIt platform to post opportunities, to list service providers, and to connect kids with activities. 
+No: Use Agaric's FindIt platform to post opportunities, list service providers, and connect kids with activities.
 
 #### Leave in words like “then,” “a,” “the,” “to,” and “that," even if you think they could be cut  
-Yes: If there is not a list set up in your MailChimp account, then you’ll need to create a list before sending your first campaign.  
-No: If there is not a list set up in your MailChimp account, you’ll need to create a list before sending your first campaign.  
-Yes: When sending a campaign, it is necessary to have a “From:” name, a “From:” address, and a subject line.  
-No: When sending a campaign, it is necessary to have a “From:” name, “From:” address, and subject line.  
-Yes: Be sure that you are truly ready to send your campaign before clicking the “Send Now” button.  
-No: Be sure you are truly ready to send your campaign before clicking the “Send Now” button.
+Yes: If there is not a test site set up, then you’ll need to create a test site before you can safely evaluate functionality changes.  
+No: If there is not a test site set up, you’ll need to create a test site before you can safely evaluate functionality changes.
+Yes: When sending an email, it is necessary to have a “From:” name, a “From:” address, and a subject line.  
+No: When sending an email, it is necessary to have a “From:” name, “From:” address, and subject line.  
+Yes: Be sure that you are truly ready to show your work to the world before pushing your changes to live.  
+No: Be sure you are truly ready to show your work to the world before pushing your changes to live.
 
 #### Avoid ambiguity and confusion
 Many words, parts of speech, and grammar mechanics we don’t think twice about have the potential to cause confusion for translators and non-native English speakers. Here are some of the big trouble spots to avoid.
 
 #### Avoid unclear pronoun references
-Yes: Many believe that buying a list of email addresses and sending to the list through MailChimp is OK. Such action can actually cause high of rates abuse, bounces, and unsubscribes. Purchasing a list and sending to it may cause your account to be suspended.
-No: Many believe that buying a list of email addresses and sending to the list through MailChimp is okay. This can actually cause high rates of abuse, bounces, and unsubscribes. It can ultimately cause your account to be suspended.
-
+Yes: Many believe that making functionality changes directly to a live site is OK. Such action can actually cause a site to break. Making functionality changes directly to a live site is not recommended.
+No: Many believe that making functionality changes directly to a live site is OK. This can cause a site to break. It is not recommended.
 #### Avoid -ing words
 In English, many different types of words end in -ing: nouns, adjectives, progressive verbs, etc. But a translator who is a non-native English speaker may not be able to recognize the distinctions and may try to translate them all in the same way.
 Because of this, we want to avoid -ing words when possible. One exception to this rule is words like “graphing calculator” and “riding lawnmower,” where the -ing word is part of a noun’s name and can’t be worked around.
 Here are some other cases where you might see -ing words, and suggestions for how to edit around them.
 
 #### Gerunds
-Yes: In this article we will talk about list subscriber collection.  
-No: In this article we will talk about getting list subscribers.  
+Yes: In this article we will talk about training participant signups.  
+No: In this article we will talk about getting training participants.  
 
 #### Adjectives
-Yes: At the top of the page, there is Freddie with a smile on his face.  
-No: At the top of the page, there is a smiling Freddie.  
+Yes: At the top of the page, there is Ben with a smile on his face.  
+No: At the top of the page, there is a smiling Ben.  
 
 #### Parts of verbs
 Yes: Several developers are currently working on that feature.