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

Thoroughly overhaul the content styleguide

Browse source
This commit is contained in:
benjamin melançon 2024-04-02 02:47:25 -04:00
parent 05c644234c
commit 096622fb56
1 changed files with 102 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

207
content-style-guide.md
View file

@ -8,32 +8,22 @@ Good content is authentic, useful, and appropriate to its context.
Agaric's voice is straightforward, bold, and irreverant.
[Write for translation](#writing-for-translation) by writing clear, straightforward English. [Write for accessibility](#writing-for-accessibility) by doing the same and by organizing information, steering clear of distractions, and being mindful of alternative ways of processing information (including non-visual).
### Writing about people
We write and build apps with a person-first perspective. Being aware of the impact of language is one way for us to live out our [values](values).
* Do not reference age or ability unless it is immediately relevant.
* Avoid gendered language and use the singular they.
* When writing about a person, use their preferred pronouns; if you do not know those, use their name.
* Related resource: [The Conscious Style Guide](https://consciousstyleguide.com/).
### Grammar and mechanics
Some people will read every word you write. Others will just scan. Help everyone by grouping related ideas together and using descriptive headers and subheaders.
Focus your message, and create a hierarchy of information. Lead with the main point or the most important content.
* Group related ideas together with descriptive headers and subheaders.
* Lead with the main point.
* Use active voice and positive language.
* Use short words and sentences.
* Avoid unnecessary modifiers.
* Use specific examples.
* Avoid vague language.
* Be consistent. Adhere to the copy patterns and style points outlined in this guide.
* Use specific examples; avoid vague language.
* Be consistent. (This guide is here to help!).
* Do not use contractions as they cheapen the content and provide difficulty for readers of other languages.
* Use the serial comma. Otherwise, use common sense. (Also known as the Oxford comma, it helps clarify when items in a list of three, four, or more things are their own items.)
* Do not use underline for emphasis, and do not use any combination of italic, bold, caps, and underline.
* Use the serial comma. (Also known as the Oxford comma, it helps clarify when items in a list of three, four, or more things are their own items.)
* Do not use underline or all-uppercase capitalization for emphasis.
* Avoid combining *italics* and **bold** (***except as last-resort extra emphasis***).
* Skip unnecessary images and when including pictures or graphics provide alt text (image descriptions).
* Lower barriers to taking action by ensuring links are descriptive and that in forms all fields have labels that are present and clear with a minimum of required fields.
* Leave out irrelevent characterizations, especially when [writing about people](#writing-about-people).
* When in doubt, read your writing out loud.
Many of these repeat or reinforce George Orwell's six rules from his essay "Politics and the English Language" (1946), and it is worth keeping all of them in mind, especially the last:
@ -45,30 +35,9 @@ Many of these repeat or reinforce George Orwell's six rules from his essay "Poli
> (v) Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
> (vi) Break any of these rules sooner than say anything barbarous.
[Much more on grammar and mechanics](#grammar-and-mechanics).
### Writing for accessibility
* Create a hierarchy, with the most important information first.
Place similar topics in the same paragraph, and clearly separate different topics with headings.
* Use plain language. Write short sentences and familiar words.
* Links should provide information on the associated action or destination. Avoid saying “click here” or “learn more.”
* Avoid using images when descriptive text will do.
* Avoid directional instructions or language that requires the reader to see the layout or design of the page.
* Label inputs on forms with clear names and use appropriate tags. Think carefully about what fields are necessary, and especially which ones you mark as required.
### Writing for translation
* Use active voice.
* Avoid double negatives.
* Do not use contractions as they cheapen the content and provide difficulty for readers that do not speak English of other languages.
* Avoid using synonyms for the same word in a single piece of writing.
* Write briefly, but do not sacrifice clarity for brevity. You may need to repeat or add words to make the meaning of your sentences clear to a translator.
* Avoid slang, idioms, and cliches.
* Avoid unnecessary abbreviations.
## Writing Goals and Principles
## Goals and Principles when writing
With every piece of content we publish, we aim to:
@ -91,7 +60,7 @@ We strive to have the same voice all the time, but our tone changes to suit the
Agaric's voice is:
* Straightforward and earnest.
* Unafraid of bold and even visionary calls to action.
* Unafraid of bold, perhaps visionary, calls to action.
* Irreverant; the human condition is too serious to take anything too seriously.
### Tone
@ -106,9 +75,15 @@ Agaric has a sense of humor, so feel free to be funny when it is appropriate and
We have been saying it from the beginning and are only half-serious about it.
## Writing About People
## Writing about people
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.
We write the same way we build software: with a person-first perspective. Being aware of the impact of language is one way for us to live out our [values](values.md).
* Do not reference age or ability unless it is immediately relevant.
* Avoid gendered language and use the singular they.
* When writing about a person, use their preferred pronouns; if you do not know those, use their name.
Write for and about other people in a way that is compassionate, inclusive, and respectful.
### Age
@ -173,8 +148,9 @@ Use the adjective "blind" to describe a person who is unable to see. Use "low vi
## 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.)
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 in this section— search if you are looking for something in particular.)
(grammar-and-mechancis-basics)=
### 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.
@ -253,25 +229,25 @@ Numbers over 3 digits get commas:
1,000
150,000
Write out big numbers in full. Abbreviate them if there are space restraints, as in a tweet or a chart: 1k, 150k.
Write out big numbers in full. Abbreviate them if there are space restraints, as in a microblog post or a chart: 1k, 150k.
#### Dates
Generally, spell out the day of the week and the month. Abbreviate only if space is an issue in the app.
Generally, spell out the day of the week and the month. Abbreviate only if space is an issue.
Saturday, January 24
Sat., Jan. 24
#### Decimals and fractions
Spell out fractions.
Yes: two-thirds
No: 2/3
Yes: two-thirds
Best: ⅔
Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.
#### Percentages
This depends on context - use the % symbol or spell out "percent" depending on which looks best.
This depends on context— use the % symbol or spell out "percent" depending on which looks best.
#### Ranges and spans
@ -324,6 +300,7 @@ the 90s
When referring to decades more than 100 years ago, be more specific:
the 1650s
the 1890s
the 1910s
#### Punctuation
@ -419,7 +396,7 @@ Use single quotation marks for quotes within quotes.
##### Semicolons
Go easy on semicolons; they usually support long, complicated sentences that could be simplified. Try an em dash (—) instead, or simply start a new sentence.
Go easy on semicolons; they usually support long, complicated sentences that could be simplified. Try an em dash (—) instead, or simply start a new sentence.
##### Ampersands
@ -433,23 +410,25 @@ Do not use ampersands unless one is part of a company or brand name.
When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.
* GIF
* PDF
* HTML
* PNG
* JPGs
When referring to a specific file, the filename should be lowercase:
* slowclap.gif
* agaric-example-org-website-proposal.pdf
* ben-twitter-profile.jpg
* micky-twitter-profile.jpg
```{seealso}
Agaric's [document versioning and filename conventions]().
```
##### Pronouns
If your subject's gender is unknown or irrelevant, use "they," "them," and "their" as a singular pronoun. Use "he/him/his" and "she/her/her" pronouns as appropriate. Do not use "one" as a pronoun.
If your subject's gender is unknown or irrelevant, use "they," "them," and "their" as a singular pronoun. Use "he/him/his" and "she/her/her" pronouns as appropriate. Do not use "one" as a pronoun.
```{seealso}
For more on writing about gender, see [Writing about people](writing-about-people).
For more on writing about gender, see [Writing about people](#writing-about-people).
```
##### Quotations
@ -466,7 +445,7 @@ Marketing team
Support department
Capitalize individual job titles when referencing to a specific role. Do not capitalize when referring to the role in general terms.
Our new Marketing Manager starts today.
All the managers ate donuts.
All the managers ate doughnuts.
Do not refer to someone as a “guru,” “rockstar,” or “wizard” unless they literally are one.
**Schools**
@ -514,8 +493,8 @@ Do not use underline formatting, which typically indicates a link, and do not us
## Write positively
Use positive language rather than negative language. One way to detect negative language is to look for words like "cannot" or "do not" (or the contractions we want to remove anyway, "can't" and "don't").
Yes: To get a donut, stand in line.
No: You can't get a donut if you don't stand in line.
Yes: To get a doughnut, go to the kitchen.
No: You can't get a doughnut if you don't go to the kitchen.
## Content Types
@ -602,11 +581,13 @@ Example: Agaric Launches Data Visualization Platform for Healthcare Providers
Every piece of content we publish is supported by a number of smaller pieces. This section lays out our style in regards to these web elements, and explains our approach to the tricky art of SEO.
(web-elements-guidelines)=
### Guidelines
#### Alt text
Alt text is a way to label images, and it is especially important for people who can’t see the images on our website. Alt text should describe the image in a brief sentence or two.
For more on how and why we use alt text, read the Accessibility section.
For more on how and why we use alt text, read the [Accessibility section](#writing-for-accessibility).
#### Buttons
@ -647,18 +628,19 @@ 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.
Provide a link when you refer to anything web-accessible that is relevant and hosted by a trusted external resources.
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.
Yes: Read the [content style guide](content-style-guide.md#links) for details.
No: Read [the content style guide](content-style-guide.md#links) for details.
If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.
If a link comes at the end of a sentence or before a comma, do not link the punctuation mark.
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 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.
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.
```{seealso}
[Baseline Styleguide: Links](making-websites/baseline-styleguide.md#links)
```
#### Lists
@ -704,7 +686,7 @@ Give every image descriptive alt text.
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.
(writing-blog-posts-basics)=
### Basics
We update the main Agaric blog a couple times every month. We generally publish:
@ -890,7 +872,7 @@ People should be able to keep up with Agaric however they choose, so we should i
### Guidelines
E-mail newsletters use our [voice and tone](#id1) and follow our [grammar and mechanics](grammar-and-mechanics), in addition to these newsletter-specific considerations.
E-mail newsletters use our [voice and tone](#voice-and-tone) and follow our [grammar and mechanics](#grammar-and-mechanics), in addition to these newsletter-specific considerations.
### Consider all elements
@ -965,7 +947,7 @@ Agaric has a presence on most major social media platforms. Here are our most ac
### 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.
Our writing for social media should generally follow the style points outlined in the [Voice and tone](#voice-and-tone) and [Grammar and mechanics](#grammar-and-mechanics) sections. Here are some additional pointers.
#### Write concisely, but clearly
@ -1003,8 +985,9 @@ We employ hashtags rarely and deliberately. We may use them to promote an event
## Writing for Accessibility
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.
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, circling helicopters) or more permanent.
(accessibility-basics)=
### 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.
@ -1019,6 +1002,16 @@ 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.
* Some people will read every word you write. Others will scan. Help everybody by grouping related ideas together and by using descriptive headers and subheaders.
* Create a hierarchy, with the most important information first.
Place similar topics in the same paragraph, and clearly separate different topics with headings.
* Use plain language. Write short sentences and familiar words.
* Links should provide information on the associated action or destination. Avoid writing "click here" or "learn more."
* Avoid using images when descriptive text will do.
* Avoid directional instructions or language that requires the reader to see the layout or design of the page.
* Label inputs on forms with clear names and use appropriate tags. Think carefully about what fields are necessary, and especially which ones you mark as required.
(accessibility-guidelines)=
### Guidelines
* Avoid directional language
@ -1055,13 +1048,13 @@ Write short sentences and use familiar words. Avoid jargon and slang. If you nee
### Use alternative 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:
The alt tag is the most basic form of image description, and it should be included on all images. The wording 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 is inside the image in detail. People who do not 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.
Supplement images with standard captions when you realize .
### Make sure closed captioning is available
@ -1073,6 +1066,7 @@ Aim for high contrast between your font and background colors. Tools in the reso
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.
(accessibility-resources)=
### Resources
* [Accessibility evaluation for web writers](http://www.4syllables.com.au/2013/05/writers-accessibility-evaluation/)
@ -1082,10 +1076,19 @@ Images should not be the only method of communication, because images may not lo
## Writing for Translation
* Use active voice.
* Avoid double negatives.
* Do not use contractions as they cheapen the content and provide difficulty for readers that do not speak English of other languages.
* Avoid using synonyms for the same word in a single piece of writing.
* Write briefly, but do not sacrifice clarity for brevity. You may need to repeat or add words to make the meaning of your sentences clear to a translator.
* Avoid slang, idioms, and cliches.
* Avoid unnecessary abbreviations.
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.
(writing-for-translation-basics)=
### 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.
@ -1100,9 +1103,10 @@ Use positive words when talking about positive situations. For example, because
Avoid contractions.
(writing-for-translation-guidelines)=
### 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 are writing something to be translated, the guidelines in this section should take precedence.
When writing for international audiences, we generally follow what is outlined in the Voice and tone and [Grammar and mechanics](#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.
#### Consider cultural differences
@ -1187,31 +1191,31 @@ No: From our backyard, we could hear the planes taking off from the airport.
* Slang, idioms, and cliches
* 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 e-mail” instead of “message us”)
* Non-standard or indirect verb usage (use “he says,” not “he’s like” or “he was all”)
* 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.")
* Verbing nouns (or otherwise converting one part of speech into another) if the usage is not common (use "Send us an e-mail" instead of "message us")
* Non-standard or indirect verb usage (use "he said," not "he was 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.
* Using multiple 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.
#### Beware words with multiple meanings
“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.
"Once" (could mean "one time," "after," "in the past," or "when")
No: Once you log in, you will see your account's dashboard.
Yes: After 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.
"Right" (could mean "correct," "the opposite of left," or "reactionary")
No: Click the right image and drag it to the right pane.
Yes: Click the correct image and drag it to the pane at right.
“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.
"Since" (could refer to a point in time, or a synonym of "because")
No: Since you already registered, this information will be filled out for you.
Yes: Because you already registered, this information will be filled out for you.
“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.)
"Require to" (could confuse the relationship between subject and object)
No: A registered account is required to post to the forum. (This could imply that people with paid accounts are required to send autoresponders.)
Yes: An account
“Has” or “have” plus past participle (could confuse the relationship between subject and object)
Yes: The folder contains sent campaigns.
@ -1223,9 +1227,9 @@ No: The folder has sent campaigns.
When writing for an international audience, use the metric system. Spell out all units and avoid abbreviation.
**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.
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 is important to specify.
Avoid colloquial phrases that relate to money, like “five-and-dime,” “greenbacks,” or “c-notes.” These will not translate well.
Avoid colloquial phrases that relate to money, like "five-and-dime," "greenbacks," or "c-notes." These will not translate well.
## Word list (specialized vocabulary)
@ -1285,13 +1289,6 @@ Originally adapted from [Mailchimp's content style guide](https://styleguide.mai
* [Marketing documentation](marketing).
* Information about [copyrights and trademarks](copyright-and-trademarks).
* [Baseline Styleguide](making-websites/baseline-styleguide.md)
* [Agaric website basics](agaric-website/basics) and [content entry on Agaric's sites](agaric-website/agaric-site-content-entry).
```
```{toctree}
---
caption: See also
---
copyright-and-trademarks
```