Menu
Open source

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).

More information ->

Grafana.GoogleDateFormat

Extends: existence

Use ‘July 31, 2016’ format, not ‘%s’.

More information ->

Grafana.GoogleEmDash

Extends: existence

Don’t put a space before or after a dash.

More information ->

Grafana.GoogleEnDash

Extends: existence

Use an em dash (’—’) instead of ‘–’.

More information ->

Grafana.GoogleExclamation

Extends: existence

Don’t use exclamation points in text.

More information ->

Grafana.GoogleGender

Extends: existence

Don’t use ‘%s’ as a gender-neutral pronoun.

More information ->

Grafana.GoogleGenderBias

Extends: substitution

Consider using ‘%s’ instead of ‘%s’.

More information ->

Grafana.GoogleLyHyphens

Extends: existence

‘%s’ doesn’t need a hyphen.

More information ->

Grafana.GoogleOptionalPlurals

Extends: existence

Don’t use plurals in parentheses such as in ‘%s’.

More information ->

Grafana.GooglePeriods

Extends: existence

Don’t use periods with acronyms or initialisms such as ‘%s’.

More information ->

Grafana.GoogleSlang

Extends: existence

Don’t use internet slang abbreviations such as ‘%s’.

More information ->

Grafana.GoogleSpacing

Extends: existence

‘%s’ should have one space.

More information ->

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’.

More information ->

Grafana.Ordinal

Extends: existence

For ordinals, write out first through ninth. For 10th on, use numerals.

More information ->

Grafana.Please

Extends: existence

It’s great to be polite, but using ‘please’ in a set of instructions is overdoing the politeness.

More information ->

Grafana.ReferTo

Extends: substitution

When linking in Markdown, use ‘%s’ instead of ‘%s’.

More information ->

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.

More information ->

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.

More information ->

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.

More information ->

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.

More information ->

Grafana.AmazonCloudWatch

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

Grafana.AmazonProductNames

Extends: conditional

Use the full Amazon product name in the first instance.

More information ->

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.”

More information ->

Grafana.CHANGELOG

Extends: substitution

Use ‘%s’ instead of ‘%s’ unless you’re referring to a specific file which has that spelling.

More information ->

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.

More information ->

Grafana.DatadogProxy

Extends: substitution

Use ‘%s’ instead of ‘%s’.

Grafana.DialogBox

Extends: substitution

Use ‘%s’ rather than ‘%s’.

More information ->

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.

More information ->

Grafana.GoogleEllipses

Extends: existence

In general, don’t use an ellipsis.

More information ->

Grafana.GoogleFirstPerson

Extends: existence

Avoid first-person pronouns such as ‘%s’.

More information ->

Grafana.GoogleHeadingPunctuation

Extends: existence

Don’t put a period at the end of a heading.

More information ->

Grafana.GoogleOxfordComma

Extends: existence

Use the Oxford comma in ‘%s’.

More information ->

Grafana.GoogleRanges

Extends: existence

Don’t add words such as ‘from’ or ‘between’ to describe a range of numbers.

More information ->

Grafana.GoogleSpelling

Extends: existence

In general, use American spelling instead of ‘%s’.

More information ->

Grafana.GoogleWill

Extends: existence

Avoid using ‘%s’.

Use present tense for statements that describe general behavior that’s not associated with a particular time.

More information ->

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.

More information ->

Grafana.Kubernetes

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

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.

More information ->

Grafana.PrometheusExporters

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

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.

More information ->

Grafana.README

Extends: substitution

Use ‘%s’ instead of ‘%s’ unless you’re referring to a specific file which has that spelling.

More information ->

Grafana.React

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

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”.

More information ->

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.

More information ->

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.

More information ->

Grafana.Wish

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

Grafana.WordList

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

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.

More information ->

Grafana.Archives

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

Grafana.GoogleContractions

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

Grafana.GooglePassive

Extends: existence

In general, use active voice instead of passive voice (’%s’).

More information ->

Grafana.GoogleSemicolons

Extends: existence

Use semicolons judiciously.

More information ->

Grafana.OAuth

Extends: substitution

Use ‘%s’ instead of ‘%s’.

More information ->

Grafana.Parentheses

Extends: existence

Use parentheses judiciously.

More information ->

Grafana.ReadabilityAutomatedReadability

Extends: metric

%s aim for below 8.

More information ->

Grafana.ReadabilityColemanLiau

Extends: metric

%s aim for below 9.

More information ->

Grafana.ReadabilityFleschKincaid

Extends: metric

%s aim for below 8.

More information ->

Grafana.ReadabilityFleschReadingEase

Extends: metric

%s aim for above 70.

More information ->

Grafana.ReadabilityGunningFog

Extends: metric

%s aim for below 10.

More information ->

Grafana.ReadabilityLIX

Extends: metric

%s aim for below 35.

More information ->

Grafana.ReadabilitySMOG

Extends: metric

%s aim for below 10.

More information ->

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.

More information ->