Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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