2020-08-21 10:43:33 -04:00 · 2020-08-21 10:43:33 -04:00 · cd1ce8a772
commit cd1ce8a772
parent 4fe2ba98eb
1 changed files with 63 additions and 29 deletions
--- a/content-style-guide.md
+++ b/content-style-guide.md
@ -504,18 +504,24 @@ 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.  
-Social media  
+
+#### Social media
+
 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: The City of Camrbidge uses Agaric's Find It platform to make it easier for people to find activities, events, and resources. Here is how it works: https://agaric.coop/work/find-it-cambridge
-See also: Writing for social media  

-#### Success message  
+```{seealso}
+[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  
@ -526,27 +532,36 @@ Example: Excellent! Your account has been created
 #### Blog post  
 What: Informative articles about Agaric work, initiatives, and announcements  
 Length: 400-800 words  
-Example: Flat Comments in Drupal 8 without Dangerous Secret Threading  
-See also: Writing blog posts
+Example: Flat Comments in Drupal 8 without Dangerous Secret Threading
+
+```{seealso}
+[Writing blog posts](#writing-blog-posts)
+```
+
+
+#### E-mail newsletter

-#### Email newsletter
 What: Email campaigns that market our services/products and inform or empower our users  
 Length: 200-1000 words  
-Example: We need one!  
-See also: Writing email newsletters
+Example: Agaric needs to finally start one!
+
+```{seealso}
+[Writing email newsletters](#writing-email-newsletters)
+```

 #### How To article
+
 What: Easily digestible content that walks users through a process or problem  
 Length: 300-1,000 words  
-Owner: Knowledge Base  
+Home: Blog  
 Example: Getting Started with Lists  
 See also: Writing technical 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
-Example: Legal: Terms of Use
+Example: Terms of Use
 See also: Writing legal content

 #### Press release
@ -927,45 +942,60 @@ Images should not be the only method of communication, because images may not lo
 * [WAVE Web Accessibility Evaluation Tool](http://wave.webaim.org/)  

 ## Writing for Translation
+
 Agaric serves users in several countries and territories, not just the United States. As our user base grows, it becomes more and more important that our content is accessible to people around the world.

-We call the process of writing copy for translation “internationalization.” This section will address things you can do to help international audiences, including translators, better comprehend your text.
+We call the process of writing copy for translation "internationalization." This section will address things you can do to help international audiences, including translators, better comprehend your text.

 ### Basics
+
 We try to write all of our content in standard, straightforward English that can be understood by users with limited English proficiency. It is much easier for a translator to clearly communicate ideas written in straightforward, uncomplicated sentences.
+
 Here are some guiding principles for writing for international audiences:
+
 Use active voice. We always aim for this, but it is especially important when writing for translation.

-Use the subject-verb-object sentence structure. It’s not used by all languages, but it’s widely recognized. That does not mean we should rely on it.
+Use the subject-verb-object sentence structure. It is not used by all languages, but it is widely recognized. That does not mean we should rely on it.

-Use positive words when talking about positive situations. For example, because a question like “Don’t you think she did a great job?” begins with a negative word, a non-native English speaker may interpret its implication as negative. A better version would be “She did a good job, right?”
+Use positive words when talking about positive situations. For example, because a question like "Don't you think she did a great job?" begins with a negative word, a non-native English speaker may interpret its implication as negative. A better version would be "She did a good job, right?"
+
+Avoid contractions.

 ### Guidelines
-When writing for international audiences, we generally follow what is outlined in the Voice and tone and Grammar and mechanics sections. But in this section more than others, some style points contradict what is stated elsewhere in the guide. If you’re writing something to be translated, the guidelines in this section should take precedence.

-### Consider cultural differences
-Agaric’s voice is conversational and informal. However, in some cultures, informal text may be considered offensive. Check with your translator to see if this is the case for the particular language you’re writing for.
+When writing for international audiences, we generally follow what is outlined in the Voice and tone and Grammar and mechanics sections. But in this section more than others, some style points contradict what is stated elsewhere in the guide. If you are writing something to be translated, the guidelines in this section should take precedence.

-The translation company should give the option to translate in a formal or informal tone, if the language allows for it. (For example, in Spanish, it is possible to write informally where tú = you or formally where usted = you.)
+#### Consider cultural differences
+
+Agaric's voice is conversational and informal. However, in some cultures, informal text may be considered offensive. Check with your translator to see if this is the case for the particular language you're writing for.
+
+Some languages have a clearer distinction between a formal or informal tone. (For example, in Spanish, it is possible to write informally where tú = you or formally where usted = you.)

 When writing text that will be translated, be careful about making references to things of local or regional importance. These may not be recognizable to readers outside the US.

-### Prioritize clarity
-Keep your copy brief, but don’t sacrifice clarity for brevity. You may need to repeat or add words to make the meaning of your sentences clear to a translator.
+#### Prioritize clarity
+
+Keep your copy brief, but do n’t sacrifice clarity for brevity. You may need to repeat or add words to make the meaning of your sentences clear to a translator.

 #### Repeat verbs that have multiple subjects.
+
 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: 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 helping verbs belonging to multiple verbs
+
+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: Most Agarics have used contractions, but Micky has not. 
 No: Most Agarics used contractions, but not Micky.  

 #### Repeat markers in a list or series
+
 Yes: Use Agaric's Find It platform to post opportunities, to list service providers, and to connect kids with activities. 
+
 No: Use Agaric's Find It 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  
@ -973,7 +1003,7 @@ No: Use Agaric's Find It platform to post opportunities, list service providers,
 Yes: If there is not a test site set up, then you will need to create a test site before you can safely evaluate functionality changes.  
 No: If there is not a test site set up, you will 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.  
+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.  
@ -998,7 +1028,7 @@ Here are some other cases where you might see -ing words, and suggestions for ho

 ##### Gerunds

-Yes: In this article we will talk about training participant signups.  
+Yes: In this article we will talk about how to encourage participants to sign up for training.  
 No: In this article we will talk about getting training participants.  

 ##### Adjectives
@ -1019,11 +1049,11 @@ No: From our backyard, we could hear the planes taking off from the airport.
 #### Other words and mechanics to avoid

 * Slang, idioms, and cliches  
-* Contractions (English contractions may not be recognizable to all translators)  
-* Shortened words, even if they’re common in English (use “application,” not “app”)  
+* Contractions (English contractions may be harder to translate)  
+* Shortened words, even if they are common in English (use “application,” not “app”)  
 * Uncommon foreign words (use "genuine,” not “bona fide”)  
 * Unnecessary abbreviations (use "for example,” not “e.g.”)  
-* Converting one part of speech into another if it isn’t already commonly used (use "Send us an email” instead of “message us”)  
+* Converting one part of speech into another if it isn’t already commonly used (use "Send us an e-mail” instead of “message us”)  
 * Non-standard or indirect verb usage (use “he says,” not “he’s like” or “he was all”)  
 * Double negatives  
 * Synonyms, generally. Do not use a lot of different words for the same thing in a single piece of writing. Instead of mixing it up with “campaign,” “newsletter,” “bulletin,” etc., pick one term and stick with it.
@ -1033,15 +1063,19 @@ No: From our backyard, we could hear the planes taking off from the airport.
 “Once” (could mean “one time,” “after,” “in the past,” or “when”)  
 Yes: After you log in, you will see your account’s Dashboard.  
 No: Once you log in, you will see your account’s Dashboard.  
+
 “Right” (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)  
 Yes: In the File Manager, click the correct image and drag it to the pane at right.  
 No: In the File Manager, click the right image and drag it to the right pane.  
+
 “Since” (could refer to a point in time, or a synonym of “because”)  
 Yes: Because you already have a complete mailing list, you can send your campaign at any time.  
 No: Since you already have complete mailing list, you can send your campaign at any time.
+
 “Require” plus an infinitive (could confuse the relationship between subject and object)  
 Yes: Autoresponders can be configured and sent from paid accounts.  
 No: A paid account is required to send autoresponders. (This could imply that users with paid accounts are required to send autoresponders.)  
+
 “Has” or “have” plus past participle (could confuse the relationship between subject and object)  
 Yes: The folder contains sent campaigns.  
 No: The folder has sent campaigns.  
@ -1054,7 +1088,7 @@ When writing for an international audience, use the metric system. Spell out all
 **Currency**
 Many countries call their currency "the dollar," but the value is going to differ between countries. The US dollar is not the same as the Canadian dollar, for example. So it’s important to specify.

-Avoid colloquial phrases that relate to money, like “five-and-dime,” “greenbacks,” or “c-notes.” These won’t translate well.
+Avoid colloquial phrases that relate to money, like “five-and-dime,” “greenbacks,” or “c-notes.” These will not translate well.

 ## Word list