From 7676bd1bee2090971a45de1aa975238af4281bc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Melan=C3=A7on?= Date: Wed, 9 Feb 2022 21:08:36 -0500 Subject: [PATCH] Improve formatting --- content-style-guide.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/content-style-guide.md b/content-style-guide.md index 2a51a7d..15bdd6f 100644 --- a/content-style-guide.md +++ b/content-style-guide.md @@ -123,12 +123,12 @@ We have been saying it from the beginning and are only half-serious about it. ### Style tips -Here are a few key elements of writing Agaric’s voice. For more, see the Grammar and mechanics section. +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. +* Use active voice; avoid passive voice. +* Avoid slang and jargon; write in plain English. **Write positively** @@ -1046,6 +1046,7 @@ We employ hashtags rarely and deliberately. We may use them to promote an event 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: @@ -1063,8 +1064,8 @@ Many of the best practices for writing for accessibility echo those for writing * 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. -Yes: “Select from these options” (with the steps listed after the title) -No: “Select from the options in the right sidebar.” +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 @@ -1095,9 +1096,10 @@ Write short sentences and use familiar words. Avoid jargon and slang. If you nee ### 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 it is 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. -* If you’re sharing a chart or graph, include the data in the alt text so people have all the important information. +* If you are sharing a chart or graph, include the data in the alt text so people have all the important information. Each browser handles alt tags differently. Supplement images with standard captions when possible.