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

Further tighten up and make styleguide consistent with our own style

Browse source
This commit is contained in:
benjamin melançon 2022-02-18 23:12:23 -05:00
parent 790b75326f
commit 2e5c575969
1 changed files with 61 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
content-style-guide.md
View file

@ -106,20 +106,6 @@ 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.
### Style tips
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.
**Write positively**
* Use positive language rather than negative language.
## 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.
@ -139,7 +125,7 @@ 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 groups of people "guys". "All" is a useful, non-gendered term for addressing groups of people.
Do not call women "girls".
@ -462,10 +448,10 @@ When referring to a specific file, the filename should be lowercase:
##### 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. Don’t 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.
For more on writing about gender, see [Writing about people](writing-about-people).
```
##### Quotations
@ -490,17 +476,17 @@ The first time you mention a school, college, or university in a piece of writin
Georgia Institute of Technology, Georgia Tech
Georgia State University, GSU
States, cities, and countries
Spell out all city and state names. Don’t abbreviate city names.
Spell out all city and state names. Do not abbreviate city names.
Per AP Style, all cities should be accompanied by their state, with the exception of: Atlanta, Baltimore, Boston, Chicago, Cincinnati, Cleveland, Dallas, Denver, Detroit, Honolulu, Houston, Indianapolis, Las Vegas, Los Angeles, Miami, Milwaukee, Minneapolis, New Orleans, New York, Oklahoma City, Philadelphia, Phoenix, Pittsburgh, St. Louis, Salt Lake City, San Antonio, San Diego, San Francisco, Seattle, Washington.
On first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a common abbreviation (European Union, EU; United Kingdom, UK).
**URLs and websites**
Capitalize the names of websites and web publications. Don’t italicize.
Avoid spelling out URLs, but when you need to, leave off the http://www.
Capitalize the names of websites and web publications. Do not italicize.
Avoid spelling out URLs, but when you need to, leave off the https://www.
## Writing about Agaric
Our company's legal entity name is **Agaric, LLC**. Our trade name is **Agaric**. Use **Agaric, LLC** only when writing legal documents or contracts. Otherwise, use **Agaric**.
Our company's legal entity name is **Agaric, LLC**. Our trade name is **Agaric**. Use **Agaric, LLC** only when writing legal documents or contracts. Otherwise, use **Agaric** or **Agaric Technology Collective**.
Always capitalize Agaric.
@ -510,7 +496,7 @@ Capitalize the proper names of Agaric platforms and projects.
## Writing about other companies
Honor companies’ own names for themselves and their products. Go by whatever is used on their official website. Unless they end with an exclamation point ('!'); that is absurd and will not be respected!
Honor companies' own names for themselves and their products. Go by whatever is used on their official website. Unless they end with an exclamation point ('!'); that is absurd and will not be respected!
Refer to a company or product as *it* (not *they*).
@ -518,29 +504,25 @@ Refer to a company or product as *it* (not *they*).
Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.
Agaric’s ops team is constantly scaling our servers to make sure our users have a great experience with our products. One way we do this is with shards, or partitions, that help us better horizontally scale our database infrastructure.
## Text formatting
Use italics to indicate the title of a long work (like a book, movie, or album) or to emphasize a word.
Dunston Checks In
Brandon really loves Dunston Checks In.
Use italics when citing an example of an element, or referencing button and navigation labels in step-by-step instructions:
When you are all done, click Send.
The familiar A/B testing variables—Subject line, From name, and Send time—have now been joined by Content, and up to 3 combinations of a single variable can now be tested at once.
Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.
Left-align text, never center or right-aligned.
Leave one space between sentences, never 2.
**Write positively**
Use positive language rather than negative language. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.
> When you are done, click *Send*.
Do not use underline formatting, which typically indicates a link, and do not use a combination of italic, bold, or all capital letters.
## 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.
No: You can't get a donut if you don't stand in line.
## Content Types
Content at Agaric takes many forms. Here’s a rundown of the types of content we most often write, the functions they serve, and the teams that handle them.
Content at Agaric takes many forms. Here is a rundown of the types of content we most often write.
### Short
@ -829,33 +811,37 @@ We don’t want to overload a reader with unnecessary information, choices to ma
### Drafting technical content
Before you begin writing a new article, reach out to a subject matter expert (like an engineer, tester, designer, researcher, or technical support advisor) to get as much information as possible. You may only use a small portion of what you learn, but it helps to have more information than you need to decide where to focus your article.
Before you begin writing a new article, reach out to a subject matter expert (like an engineer, tester, designer, researcher, or technical support advisor) to get as much information as possible. You may only use a small portion of what you learn, but it helps to have more information than you need to decide where to focus your article.
Consider how many articles are needed and what article types will best describe a new feature or tasks to the user.
Outline your article, then write a draft. Stay in touch with your subject matter expert and revise as needed for accuracy, consistency, and length.
Outline your article, then write a draft. Stay in touch with your subject matter expert and revise as needed for accuracy, consistency, and length.
When you’re happy with a draft, pass it to another technical writer for peer review. Then show it to a lead technical writer for additional review and revisions. For new content or highly complex content, send last draft to your subject matter expert for final approval.
When you are happy with a draft, pass it to another technical writer for peer review. Then show it to a lead technical writer for additional review and revisions. For new content or highly complex content, send last draft to your subject matter expert for final approval.
### Writing technical content
When writing technical content, follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some more general pointers, too.
When writing technical content, follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some more general pointers, too.
**Stay relevant to the title**
When a user clicks the title of an article, they expect to find the answer they want. Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate but related article.
#### Stay relevant to the title
When a user clicks the title of an article, they expect to find the answer they want. Do not stray too far from the title or topic at hand. Use links to make related content available. If you find you are getting too far from the intended topic, then you may need to create a separate but related article.
#### Keep headlines and paragraphs short and scannable
**Keep headlines and paragraphs short and scannable**
Focused users often scan an article for the part that will answer their particular question. Be sure headlines are short, descriptive, and parallel, to facilitate scanning.
**Use second-person and describe actions to a user**
Technical content talks to users when support agents can’t.
#### Use second-person and describe actions to a user
**Strive for simplicity and clarity**
Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate idioms or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or tangentially related information, set it aside in a Before
You Start list or Notes field.
Technical content talks to users when support agents cannot.
#### Strive for simplicity and clarity
Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate idioms or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or tangentially related information, set it aside in a Before You Start list or Notes field.
#### Provide context through embedded screenshots and GIFs
**Provide context through embedded screenshots and GIFs**
Screenshots and GIFs may not be necessary for every article or process, but can be helpful to orient new users. Crop screenshots tightly around the action to focus attention.
### Editing technical content
@ -872,7 +858,6 @@ We edit technical content based on three goals:
* Helpfulness
* Stay conversational, without using contractions.
* Avoid qualifiers that muddy meaning.
* Express understanding when appropriate.
* Craft clear transitions from section to section to orient the reader.
### Formatting technical content
@ -883,23 +868,9 @@ Technical content uses organization, capitalization, and other formatting to hel
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
Menu page, Settings page
Training Team, Coding Team
Navigate to the Modules page.
Click Save & Close.
#### 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
Import your CSV File
Match Fields
Best Practices for Lists
List Collection
List Management
Email Content and Delivery
#### Ordered Lists
@ -913,7 +884,7 @@ Use unordered lists to display examples, or multiple notes in a Notes block. If
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.
Only send when we 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.
@ -921,7 +892,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](#id3), in addition to these newsletter-specific considerations.
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.
### Consider all elements
@ -1004,18 +975,18 @@ Some social media platforms have a character limit; others do not. But for the
* Twitter: 280 characters.
* Mastodon by social.coop: 500 characters.
* Facebook: No limit, but aim for 1-2 short sentences.
* Facebook: No limit, but aim for 1–3 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.”
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 (no "4" instead of "for" or "u" for "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.
Do your best to adhere to Agaric style guidelines when you are 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.
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!" Do not 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”
@ -1042,9 +1013,9 @@ We write for a diverse audience of readers who all interact with our content in
As you write, consider the following:
* Would this language make sense to someone who doesn’t work here?
* Would this language make sense to someone who does not 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?
* If someone cannot see the colors, images, or video, is the message still clear?
* Is the markup clean and structured?
* Mobile devices with accessibility features are increasingly becoming core communication tools, does this work well on them?
@ -1053,14 +1024,14 @@ Many of the best practices for writing for accessibility echo those for writing
### 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.
* Avoid directional instructions and any language that requires the reader to see the layout or design of the page. Avoiding this is helpful for many reasons, including having the instructions still make sense after 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."
### 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 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. Drupal provides this by default.
### Use headers
@ -1084,12 +1055,12 @@ Links should provide information on the associated action or destination. Try to
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
### 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:
* 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 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 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.
@ -1127,7 +1098,7 @@ Use active voice. We always aim for this, but it is especially important when wr
Use the subject-verb-object sentence structure. It is not used by all languages, but it is widely recognized. That does not mean we should rely on it.
Use positive words when talking about positive situations. For example, because a question like "Don't you think she did a great job?" begins with a negative word, a non-native English speaker may interpret its implication as negative. A better version would be "She did a good job, right?"
Use positive words when talking about positive situations. For example, because a question like "Don't you think she did a great job?" begins with a negative word, a non-native English speaker may interpret its implication as negative. A better version would be "She did a great job, yes?"
Avoid contractions.
@ -1160,7 +1131,7 @@ No: Agaric can build your website or train your development team to build more p
#### Repeat subjects and verbs
Yes: Most Agarics have used contractions, but Micky has not.
No: Most Agarics used contractions, but not Micky.
No: Most Agarics have used contractions, but not Micky.
#### Repeat markers in a list or series
@ -1168,7 +1139,7 @@ Yes: Use Agaric's Find It platform to post opportunities, to list service provid
No: Use Agaric's Find It platform to post opportunities, list service providers, and connect kids with activities.
#### Leave in words like “then,” “a,” “the,” “to,” and “that," even if you think they could be cut
#### Leave in words like "then", "a", "the", "to", and "that", even if you think they could be cut
Yes: If there is not a test site set up, then you will need to create a test site before you can safely evaluate functionality changes.
No: If there is not a test site set up, you will need to create a test site before you can safely evaluate functionality changes.
@ -1190,7 +1161,8 @@ No: Many believe that making functionality changes directly to a live site is OK
In English, many different types of words end in -ing: nouns, adjectives, progressive verbs, etc. But a translator who is a non-native English speaker may not be able to recognize the distinctions and may try to translate them all in the same way.
Because of this, we want to avoid -ing words when possible. One exception to this rule is words like “graphing calculator” and “riding lawnmower,” where the -ing word is part of a noun’s name and can’t be worked around.
Because of this, we want to avoid -ing words when possible. One exception to this rule is words like “graphing calculator” and “riding lawnmower,” where the -ing word is part of a noun's name.
Here are some other cases where you might see -ing words, and suggestions for how to edit around them.
##### Gerunds
@ -1228,8 +1200,8 @@ No: From our backyard, we could hear the planes taking off from the airport.
#### 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.
Yes: After you log in, you will see your account's Dashboard.
No: Once 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.
@ -1317,3 +1289,11 @@ Originally adapted from [Mailchimp's content style guide](https://styleguide.mai
* Information about [copyrights and trademarks](copyright-and-trademarks).
* [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
```