From 887532d9d803a409f3703904be9db8c5d0c0806d Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Tue, 1 Aug 2023 11:03:33 -0500 Subject: [PATCH] # minor wording changes (#1385) --- docs/guides/contribute/style_guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/contribute/style_guide.md b/docs/guides/contribute/style_guide.md index 3422c041e4..6bc66cd13e 100644 --- a/docs/guides/contribute/style_guide.md +++ b/docs/guides/contribute/style_guide.md @@ -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 @@ -52,8 +52,8 @@ 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. @@ -61,13 +61,13 @@ For a more complete understanding of contributing, please consult our related gu * 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 @@ -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