diff --git a/src/word-usage.adoc b/src/word-usage.adoc index f0634f9..d5a4a37 100644 --- a/src/word-usage.adoc +++ b/src/word-usage.adoc @@ -1,9 +1,15 @@ == Word usage -Above - Avoid using. Above, below, left, and right do not translate well to screen readers. Instead, use "previous or the "following". +Above:: Avoid using directional words. Above, below, left, and right do not translate well to screen readers. Instead, use "previous or the "following". -After (once):: Use after to indicate a sequence of events. Use once to indicate one time. +Acronyms:: Acronyms and other shortened forms of words must spell out the acronym at first use in a section. Also, please add them to the [https://github.com/riscv/riscv-glossary/blob/main/src/glossary.adoc]glossary for a handy reference. + +After (once):: Use "after" to indicate a sequence of events. Use "once" to indicate "one time". + +Also:: use to mean additionally rather than alternatively. + +As:: Don't use "as" to mean "because". Don't say "Use the correct version as the wrong version can cause issues." Instead, "Use the correct version because the wrong version can cause issues." Can (might, must, may, should, shall, will):: - Use "can" to indicate capability: "This option can cause your system to fail." @@ -13,19 +19,42 @@ Can (might, must, may, should, shall, will):: - Use "must" to indicate a rquired action or condition. "The system must be powered on." - Use "shall" to indicate something that "The state of the `BUSY` bit shall change only in response to a write to the register." +Contractions:: Use contractions as they set a conversational tone. + +Following:: Don't use "following" by itself. Don't say "See the following". Instead, use "See the following list". + If (whether):: Use if as a condition, such as logic. If a, then b. Use whether to indicate choice or alternative. Event a happens, whether event b does or not. Legal:: Use only to indicate that something is allowed because of a law. "RISC-V processors are legally available." Avoid using when something is allowed. Instead, use "valid". -prior (versus "before," "previous," or "preceding"):: -- If possible, replace "prior" with "before."If you can't use "before," use "prior" as an adjective to refer to something that occurred earlier in time or with a higher order of importance. +Left (and right):: Avoid using these words if at all possible. If you do use them, use "left" and "right" and not "lefthand" or "righthand". + +Like:: Use "like" to compare or draw similarities. To provide examples, use "such as". + +Numbers:: Use Arabic for numbers greater than 10. Use words for numbers 1 through 10. Except in the following cases. +- If the numbers are values, use Arabic. "Valid input is 1-10." +- If there is a mix of numbers less and greater than 10, use Arabic. +- Use the word if the number begins a sentence. So if the number is a value, rewrite the sentence so that the number doesn't begin the sentence. + +Prior (versus "before," "previous," or "preceding"):: +- If possible, replace "prior to" with "before" as "before" is a little less formal. - Use "previous" to indicate something that occurred at an unspecified time earlier. -- Use "preceding" to indicate something that occurred immediately beforehand. +- Use "preceding" to indicate something that occurred immediately before. -Re- words:: In general, words with the prefix `re` can be written without a hyphen. The only exception is `re-create`, unless you are planning to be in a boat having fun. +Re- words:: In general, words with the prefix `re` can be written as one word without a hyphen. The only exception is `re-create`, meaning to create again. Since:: Use "since" when time is involved. "Since the invention of sliced bread, toasters became popular." Do not use it when you mean "Because". +That, which, who:: +- Use "that" (without a trailing comma) to introduce clauses that are required for the sentence to make sense. +- Use "that" even if the sentence is clear in English without it: "Verify that the computer is off." +- Use "which" (with a trailing comma) to introduce clauses that add supporting information but are not required for the sentence to make sense. +- Use "who" to introduce clauses referring to people. + +This, those, these:: Provide a noun after words such as this, those, and these. For example, "This is the output of the command." Instead use "This example is the output of the command." + Time frame:: Write as 2 words, no hyphen. +Using:: Try not to use "using" by itself. Replace with "by using" or "with". "Using" can be either a noun or a participle, which can causing translation issues. You can use "Using" at the beginning of a sentence such as "Using RISC-V standards to design your chip". +