Tightening up, consistently no contractions, no smart quotes, punctuation outside phrase quoted
This commit is contained in:
parent
94c85565bd
commit
e7e281628d
1 changed files with 27 additions and 21 deletions
|
|
@ -128,25 +128,30 @@ Here are a few key elements of writing Agaric's voice. For more, see the Grammar
|
|||
|
||||
## Writing About People
|
||||
|
||||
We write the same way we build software: with a person-first perspective. Whether you are writing for an internal or external audience, it is important to write for and about other people in a way that is compassionate, inclusive, and respectful. Being aware of the impact of your language will help make Agaric a better place to work and a better steward of our values in the world. In this section we will lay out some guidelines for writing about people with compassion, and share some resources for further learning.
|
||||
We write the same way we build software: with a person-first perspective. Whether writing for an internal or external audience, write for and about other people in a way that is compassionate, inclusive, and respectful. Being aware of the impact of our language will help make Agaric a better place to work and a better steward of our values in the world.
|
||||
|
||||
### Age
|
||||
|
||||
Do not reference a person's age unless it is relevant to what you are writing. If it is relevant, include the person's specific age, offset by commas.
|
||||
The CEO, 16, just got her driver's license.
|
||||
|
||||
Do not refer to people using age-related descriptors like “young,” “old,” or “elderly.”
|
||||
Do not refer to people using age-related descriptors like "young", "old", or "elderly".
|
||||
|
||||
### 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, do not use the words “suffer,” “victim,” or “handicapped.” “Handicapped parking” is OK. Avoid using ableist language whenever possible.
|
||||
Do not refer to a person's ability unless it is relevant to what you are 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, do not use the words "suffer," "victim," or "handicapped." "Handicapped parking" is OK.
|
||||
|
||||
Avoid ableist language.
|
||||
|
||||
### Gender and sexuality
|
||||
|
||||
Don not call groups of people “guys.” "All" is a useful, non-gendered term for addressing groups of people.
|
||||
Do not 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.
|
||||
Don not call groups of people "guys". "All" is a useful, non-gendered term for addressing groups of people.
|
||||
|
||||
Do not call women "girls".
|
||||
|
||||
Avoid gendered terms in favor of neutral alternatives, like "server” instead of “waitress” and “businessperson” instead of “businessman.”
|
||||
|
||||
Use "they" as a singular pronoun.
|
||||
|
||||
Use the following words as modifiers, but never as nouns:
|
||||
|
||||
|
|
@ -158,19 +163,19 @@ Use the following words as modifiers, but never as nouns:
|
|||
* queer
|
||||
* LGBT
|
||||
|
||||
Don not use these words in reference to LGBTQIA people or communities:
|
||||
Do not use these words in reference to LGBTQIA people or communities:
|
||||
|
||||
* homosexual
|
||||
* lifestyle
|
||||
* preference
|
||||
|
||||
Do not use “same-sex” marriage, unless the distinction is relevant to what you’re writing. Avoid using “gay marriage," instead use “marriage.”
|
||||
Do not use "same-sex" marriage, unless the distinction is relevant to what you are writing, simply use “marriage.”
|
||||
|
||||
When writing about a person, use their communicated pronouns. When in doubt, just ask for their pronouns or use their name.
|
||||
When writing about a person, use their communicated pronouns. When in doubt, ask for their pronouns or use their name.
|
||||
|
||||
### Hearing
|
||||
|
||||
Use “deaf” as an adjective to describe a person with significant hearing loss. You can also use “partially deaf” or “hard of hearing.”
|
||||
Use "deaf" as an adjective to describe a person with significant hearing loss. You can also use "partially deaf" or "hard of hearing".
|
||||
|
||||
### Medical conditions
|
||||
|
||||
|
|
@ -183,14 +188,13 @@ Do not refer to a person's mental or cognitive condition unless it is relevant t
|
|||
Do not 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.
|
||||
|
||||
Use the adjective "blind" to describe a person who is unable to see. Use "low vision" to describe a person with limited sight.
|
||||
|
||||
## 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 are looking for something in particular.)
|
||||
|
||||
|
||||
### Basics
|
||||
|
||||
Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.
|
||||
|
|
@ -254,7 +258,8 @@ They are bad! Even though they may give your writing an informal feel, they prov
|
|||
|
||||
#### Emoji
|
||||
|
||||
Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately. Keep them out of blog posts and web copy entirely.
|
||||
Keep out of blog posts and web copy entirely.
|
||||
Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately.
|
||||
|
||||
#### Numbers
|
||||
|
||||
|
|
@ -293,7 +298,7 @@ This depends on context - use the % symbol or spell out "percent" depending on w
|
|||
|
||||
#### Ranges and spans
|
||||
|
||||
Use an en-dash (–) to indicate a range or span of numbers. (On Mac: Option + - (dash). On Windows: Control + -. On Debian or Ubuntu with compose key enabled: compose + --.
|
||||
Use an en-dash (–) to indicate a range or span of numbers. (On Mac: Option + `-` (dash). On Windows: Control + `-` (dash). On Debian or Ubuntu with compose key enabled: compose + `--.` (dash dash period).
|
||||
It takes 20–30 days.
|
||||
|
||||
#### Money
|
||||
|
|
@ -348,9 +353,9 @@ the 1890s
|
|||
##### Apostrophes
|
||||
|
||||
The apostrophe's most common use is making a word possessive. If the word already ends in an s and it is singular, you also add an 's. If the word ends in an s and is plural, just add an apostrophe.
|
||||
The doughnut thief ate Sam’s doughnut.
|
||||
The doughnut thief ate Chris’s doughnut.
|
||||
The doughnut thief ate the managers’ doughnuts.
|
||||
The doughnut thief ate Sam's doughnut.
|
||||
The doughnut thief ate Chris's doughnut.
|
||||
The doughnut thief ate the managers' doughnuts.
|
||||
|
||||
```{note}
|
||||
Note the exception to this rule: the word **it**, which does not use an apostrophe for its possessive, for example: "Our competitor had all its clients' websites hacked." Agaric avoids contractions so we do not ever use **it's** but rather **it is**.
|
||||
|
|
@ -1090,7 +1095,7 @@ Write short sentences and use familiar words. Avoid jargon and slang. If you nee
|
|||
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 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 the image is serving a specific function, describe what is 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 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.
|
||||
|
|
@ -1258,7 +1263,7 @@ Many countries call their currency "the dollar," but the value is going to diffe
|
|||
|
||||
Avoid colloquial phrases that relate to money, like “five-and-dime,” “greenbacks,” or “c-notes.” These will not translate well.
|
||||
|
||||
## Word list
|
||||
## Word list (specialized vocabulary)
|
||||
|
||||
* add-on (noun, adjective), add on (verb)
|
||||
* back end (noun), back-end (adjective)
|
||||
|
|
@ -1268,6 +1273,7 @@ Avoid colloquial phrases that relate to money, like “five-and-dime,” “gree
|
|||
* cooperative
|
||||
* coworker
|
||||
* Cloudflare
|
||||
* COVID-19
|
||||
* dropdown (noun, adjective), drop down (verb)
|
||||
* e-commerce
|
||||
* e-mail
|
||||
|
|
@ -1301,7 +1307,7 @@ Avoid colloquial phrases that relate to money, like “five-and-dime,” “gree
|
|||
|
||||
* automagically
|
||||
* funnel, incentivize, leverage, disruption, thought leader, or other fluffy corporate terms
|
||||
* internets, interwebs, or any other variation of the word “internet”
|
||||
* internets, interwebs, or any other variation of the word "internet"
|
||||
* ninja, rockstar, wizard, unicorn (unless referring to a literal ninja, rockstar, wizard, or unicorn)
|
||||
* young, old, elderly, or any other word describing a person's age
|
||||
* crushing it, killing it
|
||||
|
|
|
|||
Loading…
Reference in a new issue