Skip to content

Commit

Permalink
# minor wording changes (#1385)
Browse files Browse the repository at this point in the history
  • Loading branch information
sspencerwire authored Aug 1, 2023
1 parent e1a13f4 commit 887532d
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions docs/guides/contribute/style_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ For a more complete understanding of contributing, please consult our related gu
* Periods and commas go inside quotation marks “like this,” rather than “like this”.
* The em dash {shift}+{option}+{-} has no spaces before or after—like this—and is preferred for parenthetical phrases.
* Use a serial comma before the “and” in a list of three items: “Peas, mustard, and carrots.”
* Headings should be generally made in headline-style capitalization: Capitalize the first and last words, as well as all nouns, pronouns, verbs, and adverbs. If your document works better with sentence-style capitalization, perhaps because you make frequent references to acronyms, just make it consistent within the entire document.
* Headings should be generally made in headline-style capitalization: Capitalize the first and last words, as well as all nouns, pronouns, verbs, and adverbs. If your document works better with sentence-style capitalization, perhaps because you frequently reference acronyms, make it consistent within the entire document.
* Headings do not need a period or semicolon at the end, even with sentence-style capitalization, unless ending in an abbreviation.

### Voice and Tone
Expand All @@ -52,22 +52,22 @@ For a more complete understanding of contributing, please consult our related gu
* Say what you mean in as few words as possible.
* Identify and avoid unnecessarily technical terms. Consider that your audience is mostly people who have some familiarity with the subject matter, but may not be subject-matter experts.
* Exceptions to plain language:
* For documentation addressed to newcomers or beginners, or for writing content such as a blog post, a more conversational style is appropriate.
* For documentation addressed to advanced users or API (Application Programming Interface) documentation, a more formal or terse wording style is appropriate.
* A more conversational style is appropriate for documentation addressed to newcomers or beginners or for writing content like blog posts.
* A more formal or terse wording style is appropriate for documentation addressed to advanced users or API (Application Programming Interface) documentation.
* **Inclusive language.**
* Language use evolves over time. Certain words have evolved to carry negative connotations so documentation should be rewritten to use new words.
* *Master/slave* becomes *primary/secondary* or an agreed upon organizational standard.
* *Blacklist/whitelist* becomes *blocklist/allowlist* or an agreed upon organizational standard.
* You may think of other relevant examples as you create documentation.
* When speaking of a person of *unknown* or *non-binary* gender, it is now considered acceptable to use “they” as a singular pronoun.
* When speaking of one’s capabilities, frame answers as *abilities* rather than *limitations.* For example, if you are wondering whether we have documentation about running Steam on Rocky Linux, the answer is not just “no.” Rather, “Sounds like that’s a great place for you to create something to add to our tree!”
* **Avoid contractions.** This assists with translation efforts. The exception to this is when writing something in a more conversational tone, such as blog posts or welcome instructions for new members of the community.
* **Avoid contractions.** This assists with translation efforts. The exception to this is when writing something in a more conversational tone, such as blog posts or welcome instructions for new community members.

## Formatting

### Dates

When possible use the name of the month in the format {day} {Month} {year}. However, {Month} {day}, {year} is also acceptable to resolve clarity or appearance issues. Either way, to avoid creating confusion, write out month names rather than using a series of numbers. For example: 24 January 2023, but January 24, 2023 is also acceptable—with both preferable over 1/24/2023 or 24/01/2023.
When possible use the name of the month in the format {day} {Month} {year}. However, {Month} {day}, {year} is also acceptable to resolve clarity or appearance issues. Either way, to avoid confusion, write out month names rather than a series of numbers. For example: 24 January 2023, but January 24, 2023 is also acceptable—with both preferable over 1/24/2023 or 24/01/2023.

### Single-step Procedures

Expand Down Expand Up @@ -113,7 +113,7 @@ Within Markdown, admonitions are a way to put information into a box to highligh

### Links

* Make links descriptive, so it is obvious where they will lead either from the text itself or from context. Avoid hyperlinks with names like “click here.”
* Make links descriptive, so it is obvious where they will lead from the text or context. Avoid hyperlinks with names like “click here.”
* Verify that all links work as described.

### Tables
Expand Down

0 comments on commit 887532d

Please sign in to comment.