Vale at RISC-V

Vale is an open source linting tool for prose. You can find more about Vale from the Vale website.

RISC-V uses Vale to perform various checks to ensure that the RISC-V style guidelines are followed, ensuring that our documentation is consistent.

You can find installation instructions for Vale at the Vale for RISC-V documentation GitHub repository.

AsciiDoc style for Vale

The AsciiDoc style for Vale lints common AsciiDoc syntax errors. Note that many of the AsciiDoc rules replicate features of the Visual Studio Code editor Asciidoctor plugin.

Some of the errors that the AsciiDoc rules highlight include:

  • Open attribute blocks

  • Open quoted ID values

  • Images and links that are missing accessibility alt tags

  • Missing or incorrect callouts

  • Unterminated admonition, listing, and table blocks

  • Unbalanced if statements

RISC-V style for Vale

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. For example, IBM does not contain any periods.

Case sensitive terms

Terms such as "RISC-V" and "GitHub" 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 ("and", "but", "or", "so") when you begin a sentence.

Contractions

Avoid using contractions in your documentation. Contractions can cause ambiguity with translations. You don’t have to avoid them completely though.

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. An em dash — so called because it is the length of an English capital M — sets off a comment in your text. 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 International.

Friendly terminology

It is RISC-V policy to use modern word choices for terminology that is friendly for everyone. See [Friendly Terminology](https://lf-riscv.atlassian.net/wiki/spaces/TAXX/pages/565510188/Friendly+Terminology) technical process for more information.

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.

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.

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 International specification writing is Webster’s New College dictionary. You can find it online at Webster’s New World College Dictionary.

RISC-V International 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 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 RISC-V glossary.

Using

To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not use articles and prepositions that can increase the clarity of a sentence.