agaric/documentation
10
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve formatting

Browse source
This commit is contained in:
benjamin melançon 2022-02-09 21:08:36 -05:00
parent a5aacee6b3
commit 7676bd1bee
1 changed files with 9 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
content-style-guide.md
View file

@ -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.