2020-08-21 14:29:05 -04:00 · 2020-08-21 14:29:05 -04:00 · e271fea919
commit e271fea919
parent 75344324da
1 changed files with 181 additions and 58 deletions
--- a/content-style-guide.md
+++ b/content-style-guide.md
@ -610,19 +610,21 @@ What: Easily digestible content that walks users through a process or problem
 Length: 300-1,000 words  
 Home: Blog  
 Example: Getting Started with Lists  
-See also: Writing technical content  
+
+```{seealso}
+[Writing technical content](#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  
 Example: Terms of Use
-See also: Writing legal content

 #### Press release
+
 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: Agaric Launches Data Visualization Platform for Healthcare Providers 


@ -637,24 +639,35 @@ Alt text is a way to label images, and it is especially important for people who
 For more on how and why we use alt text, read the Accessibility section.

 #### Buttons
-Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles. It’s OK to use an ampersand in button copy.
+
+Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles. It is OK to use an ampersand in button copy.
 Standard website buttons include:
-Log In  
-Sign Up Free  
-Subscribe  
-Email Us  
-Checkboxes  
+
+  * Log In
+  * Sign Up Free
+  * Subscribe
+  * Email Us
+
+#### Checkboxes
+
 Use sentence case for checkboxes.
-Drop-down menus  
+
+#### Drop-down menus
+
 Use title case for menu names and sentence case for menu items.

 #### Forms
+
 Form titles should clearly and quickly explain the purpose of the form.
+
 Use title case for form titles and sentence case for form fields.
+
 Keep forms as short as possible.
-Only request information that we need and intend to use. Don’t ask for information that could be considered private or personal, including gender. If you need to ask for gender, provide a field the user can fill in on their own, not a drop-down menu.
+
+Only request information that we need and intend to use. Don’t ask for information that could be considered private or personal, including gender. If you need to ask for gender, provide a field the user can fill in on their own, not a drop-down menu.  (Or use a comprehensive solution like the [Drupal gender field module](https://www.drupal.org/project/gender).)

 #### Headings and subheadings
+
 Headings and subheadings organize content for readers. Be generous and descriptive.  
 Headings (H1) give people a taste of what they’re about to read. Use them for page and blog titles.  
 Subheadings (H2, H3, etc.) break articles into smaller, more specific sections. They give readers avenues into your content and make it more scannable.  
@ -665,22 +678,23 @@ Use title case, unless the heading is a punctuated sentence. If the heading is a
 #### Links

 Provide a link whenever you’re referring to something on an external website.  Use links to point users to relevant content and trusted external resources.
-Don’t include preceding articles (a, an, the, our) when you link text. For example:  
+
+Do not include preceding articles (a, an, the, our) when you link text. For example:  
 Yes: Read the [content style guide](content-style-guide#links) for details.  
 No: Read [the content style guide](content-style-guide#links) for details.  

 If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.

-Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.
+Do not say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.

-Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they’re interactive, and should have a distinct active and visited state. When setting the hover state of links, be sure to include focus state as well, to help readers using assistive technologies and touch devices.
+Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they are interactive, and should have a distinct active and visited state. When setting the hover state of links, be sure to include focus state as well, to help readers using assistive technologies and touch devices.


 #### Lists

-Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number lists when the order is important, like when you’re describing steps of a process. Don’t use numbers when the list’s order doesn’t matter. 
+Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number lists when the order is important, like when you are describing steps of a process. Do not use numbers when the list's order does not matter.

-If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, don’t use punctuation, but do capitalize the first word of each item.
+If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, do not use punctuation, but do capitalize the first word of each item.

 #### Navigation

@ -708,14 +722,17 @@ Titles are (you guessed it) in title case.
 Don’t use punctuation in a title unless the title is a question.  

 #### SEO
-We write for humans, not machines. We do not use gross SEO techniques like keyword stuffing to bump search results. But we also want to make it easy for people and search engines to find and share our content. Here are some not-icky ways to do this:  
+
+We write for humans, not machines. We do not use gross SEO techniques like keyword stuffing to bump search results. But we also want to make it easy for people and search engines to find and share our content. Here are some good ways to do this:
+
 Organize your page around one topic. Use clear, descriptive terms in titles and headings that relate to the topic at hand.  
 Use descriptive headings to structure your page and highlight important information.
 Give every image descriptive alt text.  


-## Writing Blog Posts
-Agaric blog posts are written by people from all over the company, not just those with “writer” in their job titles. We love having experts from around the office blog about their work. The person most familiar with the subject is in the best position to convey it, and the writers on the marketing team can help with brainstorming and editing as needed.
+## Writing blog posts
+
+Agaric blog posts are written by people from all over the company, not just those with “writer” in their job titles. We love having people who know the most about what they do blog about their work. The person most familiar with the subject is in the best position to convey it, and other Agarics can help with brainstorming and editing as needed.


 ### Basics
@ -735,7 +752,7 @@ When writing for the blog, follow the style points outlined in the Voice and ton

 #### Be casual, but smart

-This isn’t a term paper, so there’s no need to be stuffy. Drop some knowledge while casually engaging your readers with conversational language.
+This is not a term paper, so there is no need to be stuffy. Drop some knowledge while casually engaging your readers with conversational language.

 #### Be specific

@ -749,9 +766,9 @@ Get to the important stuff right away, and don’t bury the kicker. Blog posts s

 Feel free to link away from Agaric if it helps you explain something.

-#### Make 'em laugh
+#### Make them laugh

-Agaric is a fun company, and we want our blog to reflect this. Feel free to throw in a joke here and there, or link out to a funny GIF or YouTube video when appropriate. Just do not overdo it.
+Agaric is a fun company, and we want our blog to reflect this. Feel free to throw in a joke here and there, or link out to a funny GIF or YouTube video when appropriate. Just do not overdo it or force it.

 #### Use tags and keywords

@ -872,7 +889,8 @@ 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**
+#### Capitalization
+
 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.

 Find It  
@ -881,7 +899,8 @@ Training Team, Coding Team
 Navigate to the Modules page.  
 Click Save & Close.  

-**Headings**
+#### Headings
+
 Group article content with H2s and H3s. Use H2s to organize content by higher-level topics or goals, and use H3s within each section to separate supporting information or tasks.  
 Upload a List  
 Format your CSV File  
@ -892,53 +911,146 @@ List Collection
 List Management  
 Email Content and Delivery  

-**Ordered Lists**
+#### Ordered Lists
+
 Only use ordered lists for step-by-step instructions. Separate steps into logical chunks, with no more than 2 related actions per step. When additional explanation or a screenshot is necessary, use a line break inside the list item.

-**Unordered Lists**
+#### Unordered Lists
+
 Use unordered lists to display examples, or multiple notes in a Notes block. If an unordered list comprises more than 10 items, use a table instead.

-## Writing for Social Media
-We use social media to build relationships with Agaric clients and supporters and share all the cool stuff we do. But it also creates opportunities to say the wrong thing, put off clients, and damage our brand. So we’re careful and deliberate in what we post to our social channels. This section lays out how we strike that delicate balance.
+## Writing newsletters

-### Basics
-Agaric has a presence on most major social media platforms. Here are our most active accounts and what we usually post on each:
-* Twitter: Product news, brand marketing, events, media mentions, evergreen content, “we’re hiring!” posts  
-* Facebook: Product news, brand marketing, events, media mentions, evergreen content, “we’re hiring!” posts  
-* LinkedIn: Product news, recruiting content, media mentions, evergreen content
+An e-mail newsletter is a periodic publication giving insights and updates on a topic— in our case, Agaric generally.
+
+Only send when you have something to say.
+
+```{note}
+People should be able to keep up with Agaric however they choose, so we should introduce the ability to subscribe to blog posts by e-mail as well as by RSS.  But that is different from an e-mail newsletter.
+```

 ### Guidelines
-Our writing for social media should generally follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some additional pointers, too.

-**Write short, but smart**
-Some social media platforms have a character limit; others don’t. But for the most part, we keep our social media copy short.
-Twitter: 270 characters or less (this leaves room for a manual retweet and comments)
-Facebook: No limit, but aim for 1-2 short sentences.
-Instagram: No limit, but try to keep it to 1 sentence or a short phrase. Feel free to throw in an emoji.
+E-mail newsletters use our [voice and tone](#id1) and follow our [grammar and mechanics](#id3), in addition to these newsletter-specific considerations.

-To write short, simplify your ideas or reduce the amount of information you’re sharing—but not by altering the spelling or punctuation of the words themselves. It’s fine to use the shorter version of some words, like “info” for “information.” But do not use numbers and letters in place of words, like “4” instead of “for” or “u” instead of “you.”
+### Consider all elements
+
+Every email newsletter is made up of the following elements. Make sure they’re all in place before clicking send:
+
+#### From name
+
+This is usually the company or team's name. It identifies the sender in the recipient's inbox.
+
+#### Subject line
+
+Keep your subject line descriptive. There is no perfect length, but some email clients display only the first words. Tell—don't sell—what's inside. Subject lines should be in sentence case. (Note that this is different from a headline, which you may want to include in the campaign itself.)
+
+#### Preheader text
+
+The top line of your e-mail appears beside each subject line in most inboxes. Provide the info readers need when they're deciding if they should open.
+
+#### Body copy
+
+Keep your content concise. Write with a clear purpose, and connect each paragraph to your main idea. Add images when they are helpful.
+
+#### Call to action
+
+Make the next step clear. Whether you are asking people to buy something, read something, share something, or respond to something, offer a clear direction to close your message so readers know what to do next.
+
+#### Footer
+
+All campaigns follow CAN-SPAM rules.  Include an unsubscribe link, mailing address, and permission reminder in the footer of each newsletter.
+
+### Consider your perspective
+
+When sending an e-mail newsletter from Agaric, use the third person "we." When sending a newsletter as an individual, use the first person.
+
+### Use a hierarchy
+
+Most readers will be scanning your emails or viewing them on a small screen. Put the most important information first.
+
+### Include a call to action
+
+Make the reader's next step obvious, and close each campaign with a call to action. Link to a blog post, event registration, purchase page, or signup page. You can add a button or include a text link in the closing paragraph.
+
+### Avoid unnecessary links
+
+More than 50 percent of emails are read on a mobile device. Limit links to the most important resources to focus your call to action and prevent errant taps on smaller screens.
+
+### Use alt text
+
+Some email clients disable images by default. Include an alt tag to describe the information in the image for people who are not able to see it.
+
+### Segment your audience
+
+It is exciting to send to thousands of people at once, but it is doubtful that every subscriber is interested in every topic. Segment your list to find a particular audience that's likely to react.
+
+Once you have selected an audience, adjust the language to fit their needs. For example, people who have attended trainings are more likely to understand and appreciate direct, technical terms.
+
+### Test your campaigns
+
+Use the preview mode to begin, and run an Inbox Inspection to see your newsletter in different email clients. Read your campaign out loud to yourself, then send a test to a coworker for a second look.
+
+## Writing for social media
+
+We use social media to build relationships with Agaric clients and supporters and share all the cool stuff we do. But it also creates lots of chances to say the wrong thing, to put off clients, and to make people think less of us. So we are careful and deliberate in what we post to our social channels. This section lays out how we strike that delicate balance.
+
+### Basics
+
+Agaric has a presence on most major social media platforms. Here are our most active accounts and what we usually post on each:
+
+* [Twitter](https://twitter.com/agaric): Collective news, events, paid trainings, media mentions, evergreen content, calls for collaborators.
+* [Fediverse/Mastodon](https://social.coop/@agaric): Collective news, events, paid trainings, media mentions, evergreen content, calls for collaborators.
+* [Facebook](https://www.facebook.com/agaric.collective/): Collective news, events, paid trainings, media mentions, evergreen content, calls for collaborators.
+* [LinkedIn](https://www.linkedin.com/company/agaric/): Collective news, events, paid trainings, media mentions, evergreen content, calls for collaborators.
+
+### Guidelines
+
+Our writing for social media should generally follow the style points outlined in the [Voice and tone](#id1) and [Grammar and mechanics](#id3) sections. Here are some additional pointers.
+
+#### Write concisely, but clearly
+
+Some social media platforms have a character limit; others do not.  But for the most part, we keep our social media copy short.
+
+  * Twitter: 280 characters.
+  * Mastodon by social.coop: 500 characters.
+  * Facebook: No limit, but aim for 1-2 short sentences.
+  * LinkedIn: No limit, longer posts OK.
+
+To keep your posts short, simplify your ideas or reduce the amount of information you are sharing—but not by altering the spelling or punctuation of the words themselves. It is fine to use the shorter version of some words, like “info” for “information.” But do not use numbers and letters in place of words, like “4” instead of “for” or “u” instead of “you.”
+
+Threads are fine to express more complex ideas or more related information, but ensure each post in the thread stands on its own as a coherent statement.

 ### Engagement
+
 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 @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 are giving? https://agaric.coop/blog/learn-how-migrate-drupal-8-successfully-nonprofit-technology-pre-conference-day”
+
+  * 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 are giving? https://agaric.coop/blog/learn-how-migrate-drupal-8-successfully-nonprofit-technology-pre-conference-day”
+
+Do respond promptly to people who tag us (and are not trolls).

 ### 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 whenever you are publishing social content for Agaric.
-* During major breaking news events, we turn off all promoted and scheduled social posts.  
+* Be aware of what is going on in the news whenever you are publishing social content for Agaric.
+* During major breaking news events, turn off all 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.
+## Writing for Accessibility

-## Basics
+We are 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.
+
+### Basics
 We write for a diverse audience of readers who all interact with our content in different ways. We aim to make our content accessible to anyone using a screen reader, keyboard navigation, or Braille interface, and to users of all cognitive capabilities.
+
 As you write, consider the following:
+
 * Would this language make sense to someone who doesn’t work here?  
 * Could someone quickly scan this document and understand the material?  
 * If someone can’t see the colors, images or video, is the message still clear?  
@ -947,7 +1059,7 @@ As you write, consider the following:

 Many of the best practices for writing for accessibility echo those for writing technical content, with the added complexity of markup, syntax, and structure.

-## Guidelines
+### Guidelines

 * Avoid directional language  
 * Avoid directional instructions and any language that requires the reader to see the layout or design of the page. This is helpful for many reasons, including layout changes on mobile.  
@ -956,26 +1068,33 @@ 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.

 ### Employ a hierarchy
+
 Put the most important information first. Place similar topics in the same paragraph, and clearly separate different topics with headings.
 Starting with a simple outline that includes key messages can help you create a hierarchy and organize your ideas in a logical way. This improves scannability and encourages better understanding.
 Make true lists instead of using a paragraph or line breaks.

 ### Label forms
+
 Label inputs with clear names, and use appropriate tags. Think carefully about what fields are necessary, and especially which ones you mark as required. Label required fields clearly. The shorter the form, the better.

 ### Use descriptive links
+
 Links should provide information on the associated action or destination. Try to avoid “click here” or “learn more.”

 ### Use plain language
+
 Write short sentences and use familiar words. Avoid jargon and slang. If you need to use an abbreviation or acronym that people may not understand, explain what it means on first reference.

 ### Use alt text
+
 The alt tag is the most basic form of image description, and it should be included on all images. The language will depend on the purpose of the image:  
 * If it’s a creative photo or supports a story, describe the image in detail in a brief caption.  
 * If the image is serving a specific function, describe what’s inside the image in detail. People who don’t see the image should come away with the same information as if they had.  
@ -984,18 +1103,22 @@ The alt tag is the most basic form of image description, and it should be includ
 Each browser handles alt tags differently. Supplement images with standard captions when possible.

 ### Make sure closed captioning is available
+
 Closed captioning or transcripts should be available for all videos. The information presented in videos should also be available in other formats.

 ### Be mindful of visual elements
+
 Aim for high contrast between your font and background colors. Tools in the resources section should help with picking accessible colors.

 Images should not be the only method of communication, because images may not load or may not be seen. Avoid using images when the same information could be communicated in writing.

-## Resources
+### Resources
+
 * [Accessibility evaluation for web writers](http://www.4syllables.com.au/2013/05/writers-accessibility-evaluation/)  
 * [Accessibility cheatsheet](http://bitsofco.de/2015/the-accessibility-cheatsheet/)  
 * [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.