Vale rules
Vale codifies our style guide into a series of rules that can be checked against your prose. The following is a list of all the rules that we’ve defined.
Errors
The following rules are considered errors and must be fixed.
Grafana.GoogleAMPM
Extends: existence
Use ‘AM’ or ‘PM’ (preceded by a space).
Grafana.GoogleDateFormat
Extends: existence
Use ‘July 31, 2016’ format, not ‘%s’.
Grafana.GoogleEmDash
Extends: existence
Don’t put a space before or after a dash.
Grafana.GoogleEnDash
Extends: existence
Use an em dash (’—’) instead of ‘–’.
Grafana.GoogleExclamation
Extends: existence
Don’t use exclamation points in text.
Grafana.GoogleGender
Extends: existence
Don’t use ‘%s’ as a gender-neutral pronoun.
Grafana.GoogleGenderBias
Extends: substitution
Consider using ‘%s’ instead of ‘%s’.
Grafana.GoogleLyHyphens
Extends: existence
‘%s’ doesn’t need a hyphen.
Grafana.GoogleOptionalPlurals
Extends: existence
Don’t use plurals in parentheses such as in ‘%s’.
Grafana.GooglePeriods
Extends: existence
Don’t use periods with acronyms or initialisms such as ‘%s’.
Grafana.GoogleSlang
Extends: existence
Don’t use internet slang abbreviations such as ‘%s’.
Grafana.GoogleSpacing
Extends: existence
‘%s’ should have one space.
Grafana.HTTP
Extends: substitution
Use ‘%s’ instead of ‘%s’.
The HTTP scheme is insecure and all grafana.com links must use HTTPS.
Grafana.Latin
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.Ordinal
Extends: existence
For ordinals, write out first through ninth. For 10th on, use numerals.
Grafana.Please
Extends: existence
It’s great to be polite, but using ‘please’ in a set of instructions is overdoing the politeness.
Grafana.ReferTo
Extends: substitution
When linking in Markdown, use ‘%s’ instead of ‘%s’.
Grafana.RepeatedWords
Extends: repetition
‘%s’ is repeated
Grafana.Spelling
Extends: spelling
Did you really mean ‘%s’?
The Grafana dictionary might not know of this word yet.
To add a new word, refer to Add words to the Grafana Labs dictionary. Alternatively, raise an issue and a maintainer will add it for you.
For UI elements, use bold formatting. The spell checker doesn’t check words with bold formatting.
For paths; configuration; user input; code; class, method, and variable names; statuscodes; and console output, use code formatting. The spell checker doesn’t check words with code formatting.
Warnings
The following rules are warnings and may need to be fixed or otherwise require consideration.
Grafana.Admin
Extends: substitution
Use administrator instead of admin unless it’s the name of the UI label like in the Grafana ‘Admin’ role.
Grafana.Admonitions
Extends: script
Prefer the admonition shortcode over blockquotes.
The admonition shortcode renders its content in a blockquote with consistent styling across the website.
Grafana.Agentless
Extends: substitution
Grafana Agent has been replaced by Grafana Alloy, so you shouldn’t use agent-based terminology.
If you’re talking about why and how to send signals directly from an application to Grafana Cloud, prefer no-collector to agentless.
This is consistent with OTel documentation.
Grafana.AllowsTo
Extends: substitution
Did you mean ‘%s’ instead of ‘%s’?
Allows to is a common wording error.
Grafana.AltText
Extends: script
All images must have alt text.
Grafana.AmazonCloudWatch
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.AmazonProductNames
Extends: conditional
Use the full Amazon product name in the first instance.
Grafana.AndOr
Extends: existence
Avoid writing and/or except when space is limited, such as in tables.
Often, ‘and’ implies ‘or’, so you don’t need to write both words.
If you need to specify both in your content, write something like “You can export raw events, processed events, or both.”
Grafana.ApacheProjectNames
Extends: conditional
Use the full Apache project name in the first instance.
Grafana.CHANGELOG
Extends: substitution
Use ‘%s’ instead of ‘%s’ unless you’re referring to a specific file which has that spelling.
Grafana.CommandLinePrompts
Extends: script
Don’t add $ or # as prompts before commands.
Make it easy for users to copy and paste commands.
Also, don’t use # to include comments in commands.
That explanation should be outside of the code block.
Grafana.DatadogProxy
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.DialogBox
Extends: substitution
Use ‘%s’ rather than ‘%s’.
Grafana.DocumentationTeam
Extends: substitution
Use ‘%s’ rather than ‘%s’.
Grafana.Gerunds
Extends: script
For a task-based heading, start with a bare infinitive, also known as a plain form or base form verb. In English, the imperative mood also uses the base form verb, so it looks the same as the bare infinitive.
Task-based headings are frequently used in quickstarts, how-to documents, and tutorials.
For a conceptual or non-task-based heading, use a noun phrase that doesn’t start with an -ing verb.
Noun-phrase headings are frequently used in concept documentation.
Grafana.GoogleEllipses
Extends: existence
In general, don’t use an ellipsis.
Grafana.GoogleFirstPerson
Extends: existence
Avoid first-person pronouns such as ‘%s’.
Grafana.GoogleHeadingPunctuation
Extends: existence
Don’t put a period at the end of a heading.
Grafana.GoogleOxfordComma
Extends: existence
Use the Oxford comma in ‘%s’.
Grafana.GoogleProductNames
Extends: conditional
Use the full Google product name in the first instance.
Grafana.GoogleRanges
Extends: existence
Don’t add words such as ‘from’ or ‘between’ to describe a range of numbers.
Grafana.GoogleSpelling
Extends: existence
In general, use American spelling instead of ‘%s’.
Grafana.GoogleWill
Extends: existence
Avoid using ‘%s’.
Use present tense for statements that describe general behavior that’s not associated with a particular time.
Grafana.Headings
Extends: capitalization
Use sentence-style capitalization for ‘%s’.
If your heading contains capitalized words that represent product names, you need to add those words as exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Grafana/Headings.yml for them to be considered correctly cased.
Vale considers multi-word exceptions such as Grafana Enterprise Metrics as a single correctly cased word.
Grafana.Kubernetes
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.OK
Extends: existence
Don’t use any variation of okay in prose. The exceptions are when you’re referencing or quoting:
- A user interface
- HTTP status codes or other code
Grafana.ProductPossessives
Extends: existence
Don’t form a possessive from a feature name, product name, or trademark, regardless of who owns it. Instead, use the name as a modifier or rewrite to use a word like of to indicate the relationship.
Grafana.PrometheusExporters
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.Quickstart
Extends: substitution
Use the compound adjective without a hyphen whether the noun is implied or explicit. For example, you can use quickstart guide or just quickstart.
Grafana.README
Extends: substitution
Use ‘%s’ instead of ‘%s’ unless you’re referring to a specific file which has that spelling.
Grafana.React
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.SQL
Extends: substitution
Use ‘%s’ instead of ‘%s’.
The article—a or an—that you use before the acronym SQL depends on how the word is pronounced.
When referring to the product Microsoft SQL Server, SQL should be pronounced “sequel”. In this case, use the article ‘a’, as in “a SQL Server analysis”.
When referring to the term in any other context, such as SQL databases, errors, or servers, SQL should be pronounced “ess-cue-el”. In this case, use the article ‘an’, as in “an SQL error”.
Grafana.Shortcodes
Extends: script
Prefer {{< admonition type="<TYPE>" >}}.
It has the most consistent semantics.
The percent syntax is used for special behavior that isn’t required with this shortcode.
Grafana.SmartQuotes
Extends: script
Avoid smart quotes in the source file, especially in code blocks.
Replace all smart double quotes like " or " with ".
Replace all smart single quotes like ', ', or ' with '.
In some contexts, Unicode characters aren’t supported and break configurations.
The website renders paired quotes using smart quotes in paragraphs.
Grafana.We
Extends: existence
Use first person plural pronouns like ‘%s’ carefully.
Don’t use ‘we’ when you’re talking about the reader, instead use ‘you’.
It’s OK to use ‘we’ when you’re talking about Grafana Labs.
Grafana.Wish
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.WordList
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Suggestions
The following rules are suggestions to consider a certain point of style.
Grafana.Acronyms
Extends: conditional
Spell out ‘%s’, if it’s unfamiliar to the audience.
Grafana.Archives
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.DropDown
Extends: substitution
Use drop-down rather than dropdown or drop down.
Use drop-down as a modifier rather than as a standalone noun. For example: drop-down menu.
Grafana.GoogleContractions
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.GooglePassive
Extends: existence
In general, use active voice instead of passive voice (’%s’).
Grafana.GoogleSemicolons
Extends: existence
Use semicolons judiciously.
Grafana.OAuth
Extends: substitution
Use ‘%s’ instead of ‘%s’.
Grafana.Parentheses
Extends: existence
Use parentheses judiciously.
Grafana.ReadabilityAutomatedReadability
Extends: metric
%s aim for below 8.
Grafana.ReadabilityColemanLiau
Extends: metric
%s aim for below 9.
Grafana.ReadabilityFleschKincaid
Extends: metric
%s aim for below 8.
Grafana.ReadabilityFleschReadingEase
Extends: metric
%s aim for above 70.
Grafana.ReadabilityGunningFog
Extends: metric
%s aim for below 10.
Grafana.ReadabilityLIX
Extends: metric
%s aim for below 35.
Grafana.ReadabilitySMOG
Extends: metric
%s aim for below 10.
Grafana.Timeless
Extends: existence
Avoid using ‘%s’ to keep the documentation timeless.
In general, document the current version of a product or feature.
It reduces the maintenance required to keep documentation up to date. It avoids assuming the reader is familiar with earlier versions of the product.
If you’re writing procedural or time-stamped content such as press releases, blog posts, or release notes, such time-based words and phrases are OK.
Last reviewed: August 8, 2024
