From c85a3c4f7a4013ca2971e03c453d740227269ce0 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Fri, 25 Apr 2025 09:56:27 -0500 Subject: [PATCH 1/3] Update vale.adoc Adding in options for review Signed-off-by: Kersten Richter --- src/vale.adoc | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/src/vale.adoc b/src/vale.adoc index eb3753d..16972d9 100644 --- a/src/vale.adoc +++ b/src/vale.adoc @@ -24,3 +24,98 @@ Some of the errors that the AsciiDoc rules highlight include: The RISC-V style for Vale enforces the rules that are set by the RISC-V style guidelines. +=== Abbreviations + +Do not use punctuation in abbreviations. + +=== Anthropomorphism + +Anthropomorphism is granting abilities to inanimate objects, such as "This code allows you to enable access." Instead, make the user the focus of the sentence: "You can use this code to enable access." + +=== Camel case + +If you are using Camel case (`camelCase`), consider using backticks. + +=== Case sensitive terms + +Terms such as RISC-V are case sensitive. If your usage is in code, then be sure to place back ticks around the code phrase. + +=== Conjunctions + +Do not overuse conjunctions when you begin a sentence, including the following conjunctions: + +* And +* But +* Or +* So + +=== Contractions + +Avoid using contractions in Extension documentation. Contractions can cause ambiguity with translations. + +=== Ellipses + +Avoid ellipses (...) to indicated omitted words. Instead, spell out the complete phrase or use words such as "and so on" to indicate that a list is not complete. + +=== Em dashes + +Avoid em dashes. Instead use commas, parenthesis, or colons. + +=== First person + +Do not use words such as "I" or "we", unless you are indeed speaking on behalf of all of RISC-V. + +=== Gender neutral language + +Avoid using language that specifies a gender, such as "he" or "woman". Instead, use words such as "the author" or "human". + +=== Heading punctuation + +Do not use punctuation in headings. + +=== Heading + +Headings use Title case: all nouns, verbs, adjectives, and adverbs are capitalized. Do not capitalize conjunctions, prepositions, or articles. + +=== Hyphens + +Do not use hyphens unless that usage is approved. See Spelling. + +=== Merge conflict markers + +Do not include any Git merge conflict markers in your source text. For example, `<<<<<<< HEAD`. + +=== Oxford comma + +Use the Oxford comma. It saves lives. + +=== Pascal case + +If you are using Pascal case (`PascalCase`), consider using backticks. + +=== Repeated words + +Words such as "the" or "and" can end up duplicated in text. + +=== Sentence length + +Try to keep sentences to an average of 32 words or fewer, and vary sentence lengths. + +=== Slash + +Rather than use a slash, use either "or" or "and". + +=== Spacing + +Use one space between words and after the end of sentences. + +=== Spelling + +The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary]. + +RISC-V works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires. If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary]. + +=== Using + +To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not omit articles and prepositions that can increase the clarity of a sentence. + From e1933c7146ddb46a15eb465db7d54460ef287acc Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Wed, 30 Apr 2025 15:01:28 -0500 Subject: [PATCH 2/3] Update src/vale.adoc Signed-off-by: Kersten Richter --- src/vale.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/vale.adoc b/src/vale.adoc index 16972d9..dd18cc5 100644 --- a/src/vale.adoc +++ b/src/vale.adoc @@ -26,7 +26,7 @@ The RISC-V style for Vale enforces the rules that are set by the RISC-V style gu === Abbreviations -Do not use punctuation in abbreviations. +Do not use punctuation in abbreviations. For example, IBM does not contain any periods. === Anthropomorphism From 76a90a3bd755125a3df36aa7384ee99b78f84c94 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Wed, 30 Apr 2025 15:13:04 -0500 Subject: [PATCH 3/3] Update src/vale.adoc Signed-off-by: Kersten Richter --- src/vale.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/vale.adoc b/src/vale.adoc index dd18cc5..f95fc22 100644 --- a/src/vale.adoc +++ b/src/vale.adoc @@ -63,7 +63,7 @@ Avoid em dashes. Instead use commas, parenthesis, or colons. === First person -Do not use words such as "I" or "we", unless you are indeed speaking on behalf of all of RISC-V. +Do not use words such as "I" or "we", unless you are indeed speaking on behalf of all of RISC-V International. === Gender neutral language