Red Hat Style for Vale reference guide
Comprehensive reference documentation for all Vale rules included in the RedHat style. This guide provides detailed information about each rule, including what it checks, examples of violations, and how to resolve them. Use this guide to understand Vale alerts and learn the specific style requirements for Red Hat documentation.
Abbreviations
Do not use periods in all-uppercase abbreviations.
Case sensitive terms
- Alert level
-
error
Use the correct spelling and case for these case sensitive terms.
Conjunctions
Do not overuse beginning sentences with conjunctions.
Conscious language
Use conscious language.
Contractions
Avoid contractions.
Definitions
Define acronyms and abbreviations on first occurrence if they are likely to be unfamiliar.
Do not use terms
- Alert level
-
Error
Do not use error terms. Use the correct term as described in Red Hat Supplementary Style Guide (SSG).
Ellipses
Avoid ellipsis (…) except to indicate omitted words.
Em dashes
Do not use em dashes. Use punctuation marks such as commas, parentheses, or colons instead.
Heading punctuation
Do not use end punctuation in headings.
Headings
Use sentence-style capitalization in headings.
Hyphens
In most cases, do not use a hyphen to connect a prefix to a word.
Note
To determine whether to hyphenate, consult the Red Hat supplementary style guide for product documentation, the Word usage list and Hyphens sections in IBM Style, and the Merriam-Webster dictionary.
Merge conflict markers
Do not include Git merge conflict markers in source code. For example, <<<<<<< HEAD.
Oxford comma
Use the Oxford comma.
Pascal case and Camel case
Consider wrapping Pascal case or Camel case API resources, system items, daemons, or service names in backticks.
Passive Voice
Avoid the passive voice where possible. Active voice focuses on the performer of the action and is often clearer, shorter, and more direct than the passive voice.
According to the IBM Style Guide, the passive voice is acceptable in the following situations:
-
When the system performs the action
-
When it is more appropriate to focus on the receiver of the action
-
When you want to avoid blaming the user for an error, such as in an error message
-
When the information is clearer in the passive voice
-
When the information requires the passive voice, for example, glossary definitions
According to the Red Hat supplementary style guide for product documentation, you can use the passive voice in prerequisites.
Product-centric writing
Do not use product-centric writing to grant abilities to inanimate objects. Where possible, make the user the subject of the sentence.
Readability grade
Try to write paragraphs that have a calculated Flesch–Kincaid grade level below the recommended value of 9.
Release notes
For release notes, consider using Before this update or With this update.
Repeated words
Small words such as "and" or "the" get duplicated easily, especially when shuffling sentence parts around or adding line breaks.
Self-referential text
Avoid using self-referential text such as This chapter or This module.
Sentence length
Try to keep sentences to an average of 32 words or fewer, and vary sentence lengths.
Simple words
Use simple verbs and tenses. Use simple language.
Slash
Use either or or and rather than a slash (/).
Smart quotation marks
Do not use smart quotation marks (‘, ’, ‟, ″, ‶) in original body copy.
Use straight quotation marks.
Spacing
Keep one space between words.
Spelling
Use correct American English spelling.
Symbols
Do not use ampersands (&) or exclamation marks (!) in original body copy.
Error terms
- Alert level
-
Error
Do not use error terms. Use the correct term as described in Red Hat Supplementary Style Guide (SSG).
Suggestion terms
- Alert level
-
Suggestion
Depending on the context, consider using the suggested term as described in Red Hat Supplementary Style Guide (SSG).
Warning terms
- Alert level
-
Warning
Use the correct term as described in Red Hat Supplementary Style Guide (SSG), unless updating existing content that uses the term.
User-replaced values
Ensure that user-replaced values have the following characteristics:
-
Surrounded by angle brackets (
< >) -
Separated by underscores (
_) for multi-word values -
Lowercase, unless the rest of the related text is uppercase or another capitalization scheme
-
Italicized
-
If the user-replaced value is referencing a value in code or in a command that is normally monospace, also use monospace for the user-replaced value
By 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.