Lint prose with the Vale linter on Grafana Labs

Vale rules

Tue, 25 Jun 2024 00:00:00 +0000

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\d{1,2}[AP]M\b
\d{1,2} ?[ap]m\b
\d{1,2} ?[aApP]\.[mM]\.

More information ->

Grafana.GoogleDateFormat

Extends: existence

Use ‘July 31, 2016’ format, not <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}
\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}

More information ->

Grafana.GoogleEmDash

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\s[—–]\s

More information ->

Grafana.GoogleEnDash

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

–

More information ->

Grafana.GoogleGender

Extends: existence

Don’t use <CURRENT TEXT> as a gender-neutral pronoun.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

he/she
s/he
$s$he

More information ->

Grafana.GoogleGenderBias

Extends: substitution

Consider using <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`(?:alumnae\|alumni)`	`graduates`
`(?:alumna\|alumnus)`	`graduate`
`air(?:m[ae]n\|wom[ae]n)`	`pilot(s)`
`anchor(?:m[ae]n\|wom[ae]n)`	`anchor(s)`
`authoress`	`author`
`camera(?:m[ae]n\|wom[ae]n)`	`camera operator(s)`
`door(?:m[ae]\|wom[ae]n)`	`concierge(s)`
`draft(?:m[ae]n\|wom[ae]n)`	`drafter(s)`
`fire(?:m[ae]n\|wom[ae]n)`	`firefighter(s)`
`fisher(?:m[ae]n\|wom[ae]n)`	`fisher(s)`
`fresh(?:m[ae]n\|wom[ae]n)`	`first-year student(s)`
`garbage(?:m[ae]n\|wom[ae]n)`	`waste collector(s)`
`lady lawyer`	`lawyer`
`ladylike`	`courteous`
`mail(?:m[ae]n\|wom[ae]n)`	`mail carriers`
`man and wife`	`husband and wife`
`man enough`	`strong enough`
`mankind`	`human kind\|humanity`
`manmade`	`manufactured`
`manpower`	`personnel`
`middle(?:m[ae]n\|wom[ae]n)`	`intermediary`
`news(?:m[ae]n\|wom[ae]n)`	`journalist(s)`
`ombuds(?:man\|woman)`	`ombuds`
`oneupmanship`	`upstaging`
`poetess`	`poet`
`police(?:m[ae]n\|wom[ae]n)`	`police officer(s)`
`repair(?:m[ae]n\|wom[ae]n)`	`technician(s)`
`sales(?:m[ae]n\|wom[ae]n)`	`salesperson or sales people`
`service(?:m[ae]n\|wom[ae]n)`	`soldier(s)`
`steward(?:ess)?`	`flight attendant`
`tribes(?:m[ae]n\|wom[ae]n)`	`tribe member(s)`
`waitress`	`waiter`
`woman doctor`	`doctor`
`woman scientist[s]?`	`scientist(s)`
`work(?:m[ae]n\|wom[ae]n)`	`worker(s)`

More information ->

Grafana.GoogleLyHyphens

Extends: existence

<CURRENT TEXT> doesn’t need a hyphen.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\b[^\s-]+ly-\w+\b

More information ->

Grafana.GoogleOptionalPlurals

Extends: existence

Don’t use plurals in parentheses such as in <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\b\w+$s$

More information ->

Grafana.GooglePeriods

Extends: existence

Don’t use periods with acronyms or initialisms such as <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\b(?:[A-Z]\.){3,}

More information ->

Grafana.GoogleSlang

Extends: existence

Don’t use internet slang abbreviations such as <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

tl;dr
ymmv
rtfm
imo
fwiw

More information ->

Grafana.GoogleSpacing

Extends: existence

<CURRENT TEXT> should have one space.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

[a-z][.?!] {2,}[A-Z]
[a-z][.?!][A-Z]

More information ->

Grafana.Latin

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`e\.?g[,.]?`	`for example`
`i\.?e[,.]?`	`that is`

More information ->

Grafana.Ordinal

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

1st
2nd
3rd
4th
5th
6th
7th
8th
9th

More information ->

Grafana.Paragraphs

Extends: script

br elements must be used only for line breaks that are actually part of the content, as in poems or addresses.

In tables, instead of br elements, use p for paragraphs, and ul or ol for list items.

More information ->

Grafana.Please

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

please

More information ->

Grafana.ReferTo

Extends: substitution

When linking in Markdown, use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`Check out \[`	`Refer to [`
`See \[`	`Refer to [`
`check out \[`	`refer to [`
`see \[`	`refer to [`

More information ->

Grafana.Relref

Extends: script

Don’t use the relref shortcode for any links as they don’t follow redirects and have confusing semantics.

Instead use one of the links described in links.

More information ->

Grafana.RepeatedWords

Extends: repetition

<CURRENT TEXT> is repeated

Grafana.Spelling

Extends: spelling

Did you really mean <CURRENT TEXT>?

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 <REPLACEMENT TEXT> instead of <CURRENT TEXT> unless it’s the name of the UI label like in the Grafana ‘Admin’ role.

Current text	Replacement text
`admin`	`administrator`

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

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

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.

Current text	Replacement text
`agentless`	`no-collector`

More information ->

Grafana.AllowsTo

Extends: substitution

Did you mean <REPLACEMENT TEXT> instead of <CURRENT TEXT>?

Allows to is a common wording error.

Current text	Replacement text
`allows to`	`allows you to\|makes it possible to`

Grafana.AltText

Extends: script

All images must have alt text.

More information ->

Grafana.AmazonCloudWatch

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`AWS CloudWatch`	`Amazon CloudWatch`
`Cloudwatch`	`CloudWatch`
`aws CloudWatch`	`Amazon CloudWatch`
`cloudWatch`	`CloudWatch`
`cloudwatch`	`CloudWatch`

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

and/or

More information ->

Grafana.ApacheProjectNames

Extends: conditional

Use the full Apache project name in the first instance.

More information ->

Grafana.CHANGELOG

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT> unless you’re referring to a specific file which has that spelling.

Current text	Replacement text
`[Cc]hangelog`	`CHANGELOG`
`[Cc]hangelog\.md`	`CHANGELOG.md`
`[Cc]hangelogs`	`CHANGELOGs`

More information ->

Grafana.CommandLinePrompts

Extends: script

Don’t add $ or # as prompts before commands so users can copy and paste them.

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 <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`Datadog Proxy`	`Datadog proxy`
`[tT]he [Dd]atadog proxy`	`Datadog proxy`

Grafana.DialogBox

Extends: substitution

Use <REPLACEMENT TEXT> rather than <CURRENT TEXT>.

Current text	Replacement text
`dialog box appears`	`dialog box opens`
`dialog(?! box)`	`dialog box`
`modal`	`dialog box`

More information ->

Grafana.DocumentationTeam

Extends: substitution

Use <REPLACEMENT TEXT> rather than <CURRENT TEXT>.

Current text	Replacement text
`[Dd]ocs? (?:[Ss]quad\|[Tt]eam)`	`the Grafana Labs documentation team`
`[Dd]ocumentation (?:[Ss]quad\|Team)`	`the Grafana Labs documentation team`

Grafana.EndToEnd

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`[eE]2[eE]`	`end-to-end`

More information ->

Grafana.Exclamation

Extends: existence

Avoid exclamation points in text, except in rare really exciting moments.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\w+!(?:\s|$)

More information ->

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.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

\.\.\.

More information ->

Grafana.GoogleFirstPerson

Extends: existence

Avoid first-person pronouns such as <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

(?:^|\s)I\s
(?:^|\s)I,\s
\bI'm\b
\bme\b
\bmy\b
\bmine\b

More information ->

Grafana.GoogleHeadingPunctuation

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

[a-z0-9][.]\s*$

More information ->

Grafana.GoogleProductNames

Extends: conditional

Use the full Google product name in the first instance.

More information ->

Grafana.GoogleRanges

Extends: existence

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

(?:from|between)\s\d+\s?-\s?\d+

More information ->

Grafana.GoogleSpelling

Extends: existence

In general, use American spelling instead of <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

(?:\w+)nised?
colour
labour
centre

More information ->

Grafana.GoogleWill

Extends: existence

Avoid using <CURRENT TEXT>.

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

will

More information ->

Grafana.GrafanaCom

Extends: existence

Don’t use grafana.com, instead use one of the following:

If you’re talking about Grafana Cloud, use Grafana Cloud.
If you’re talking about the company, use Grafana Labs.
If you’re linking to a page on the website, use the page title or the full URL including scheme. For example, https://grafana.com/.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

grafana\.com

Grafana.Headings

Extends: capitalization

Use sentence-style capitalization for <CURRENT TEXT>.

Vale considers multi-word exceptions such as Grafana Enterprise Metrics as a single correctly cased word.

If your heading contains capitalized words that represent product names, you need to add those words to the Grafana dictionary or the list of static exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Headings.jsonnet for them to be considered correctly cased.

More information ->

Grafana.Kubernetes

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`[Kk]ubectl`	`kubectl`
`[Kk]ubelet`	`kubelet`
`[Kk]ubernetes deployment`	`Kubernetes Deployment`
`cron job`	`CronJob`
`d[ae][ae]mon[Ss]et`	`DaemonSet`
`pod`	`Pod`
`replica[Ss]et`	`ReplicaSet`
`stateful[Ss]et`	`StatefulSet`

More information ->

Grafana.MetaMonitoring

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`meat ?monitoring`	`meta-monitoring`
`meta ?monitoring`	`meta-monitoring`

More information ->

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

<CURRENT TEXT> was matched by one or more of the following regular expressions:

O.K.
OK
ok
Ok
Okay
okay
A-OK
hokay
k
keh
kk
M'kay
oka
okeh
Okie dokie
Okily Dokily

More information ->

Grafana.PalantirProductNames

Extends: conditional

Use the full Palantir product name in the first instance.

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.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

ADOT's
AI Observability's
Agent's
Alloy's
ARN's
Asserts'
Atlassian's
AWS's
AWS Distro for OpenTelemetry Collector's
AWS X-Ray's
Beyla's
BoringCrypto's
Catchpoint's
CentOS's
CloudWatch's
Codespaces'
CPython's
Data Firehose's
Databricks'
Datadog's
Dynatrace's
EKS's
Elastic Kubernetes Service's
Entra's
Figma's
Firehose's
FreeBSD's
GEM's
GKE's
Git's
GitHub's
GitLab's
GNU's
Grafana's
Gravatar's
Graylog's
Gunicorn's
hashmod's
IBM's
InfluxDB's
Jaeger's
Jira's
JMESPath's
journald's
Jsonnet's
Keycloak's
Kibana's
Killercoda's
Kinesis'
Kotlin's
KQL's
Kubernetes'
Kubernetes Engine's
Kusto's
Kustomize's
LangChain's
launchd's
Logs Drilldown's
Loki's
Lucene's
Markdown's
Memcached's
Metrics Drilldown's
Mesos'
Mimir's
Moodle's
MySQL's
Netlify's
Netlink's
Okta's
OnCall's
OpenAI's
OpenShift's
OpenTelemetry's
Opsgenie's
OTel's
PagerDuty's
Parca's
PDC's
Phlare's
Pinecone's
Podman's
Postgres'
PostgreSQL's
pprof's
Profiles Drilldown's
Prometheus'
Promtail's
Pyroscope's
RCA workbench's
RDS's
Relational Database Service's
React's
Redis'
RHEL's
Rollup's
RudderStack's
Sensu's
Sensu Go's
Splunk's
SSM's
Statuspage's
SUSE's
Tailscale's
Team Sync's
Tempo's
Thanos'
Threema's
Timestream's
Traces Drilldown's
Velero's
Vercel's
Vite's
VMware's
Webex's
WildFly's
windows_exporter's
YugabyteDB's
Zabbix's
Zendesk's
Zipkin's

More information ->

Grafana.PrometheusExporters

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`[Nn]ode exporter`	`Node Exporter`

More information ->

Grafana.Quickstart

Extends: substitution

Use the compound adjective <REPLACEMENT TEXT> without a hyphen instead of <CURRENT TEXT> whether the noun is implied or explicit. For example, you can use quickstart guide or just quickstart.

Current text	Replacement text
`quick start`	`quickstart`

More information ->

Grafana.README

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT> unless you’re referring to a specific file which has that spelling.

Current text	Replacement text
`[Rr]eadme`	`README`
`[Rr]eadme\.md`	`README.md`
`[Rr]eadmes`	`READMEs`

More information ->

Grafana.React

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`[Rr]eact[. ]?[Jj][Ss]`	`React`

More information ->

Grafana.SQL

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

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

Current text	Replacement text
`[Aa] SQL server`	`an SQL server\|a SQL Server`
`[Aa] SQL(?! [Ss]erver)`	`an SQL`
`[Aa]n SQL Server`	`a SQL Server`

More information ->

Grafana.SelfManaged

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT> when talking about Grafana deployment methods.

Current text	Replacement text
`on-prem(?:ise)?`	`self-managed`
`self-hosted`	`self-managed`

More information ->

Grafana.Shortcodes

Extends: script

Prefer {{< and >}} instead of {{% and %}}

It has the most consistent semantics.

The percent syntax is used for special behavior that isn’t required with this shortcode.

More information ->

Grafana.Simple

Extends: existence

Avoid the word easy or simple – what might be simple for you might not be simple for others.

Try eliminating this word from the sentence because usually you can convey the same meaning without it.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

easy(?![ -]to[ -]understand)
easily
simple
simply

More information ->

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

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`wish`	`need\|want`

More information ->

Grafana.WordList

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`(?:(?<!Data )Firehose\|Kinesis Data Firehose\|Kinesis Firehose)`	`Data Firehose`
`(?:SHA-1\|HAS-SHA1)`	`SHA-1`
`(?:WiFi\|wifi)`	`Wi-Fi`
`(?:[Oo]penshift\|openShift)`	`OpenShift`
`(?:[eE]-mail)`	`email`
`(?:[jJ][mM][eE][sS]p\|jmesP)ath`	`JMESPath`
`(?:[oO]pentelemetry\|openTelemetry)`	`OpenTelemetry`
`(?:alert[Mm]anager\|[Aa]lert [Mm]anager\|AlertManager)`	`Alertmanager`
`(?:cell ?phone\|smart ?phone)`	`phone\|mobile phone`
`(?:content\|media)-?type`	`media type`
`(?:file ?path\|path ?name)`	`path`
`(?:file ?path\|path ?name)s`	`paths`
`(?:github\|gitHub\|Github)`	`GitHub`
`(?:gitlab\|gitLab\|Gitlab)`	`GitLab`
`(?:hamburger menu\|kebab menu)`	`menu icon`
`(?:java[Ss]cript\|Javascript)`	`JavaScript`
`(?:kill\|terminate\|abort)`	`stop\|exit\|cancel\|end`
`(?<!kube-)prometheus`	`Prometheus`
`(?<!lambda-)promtail`	`Promtail`
`GME`	`GEM`
`Grafana AI observability`	`Grafana AI Observability`
`HTTPs`	`HTTPS`
`Influx[Dd]b`	`InfluxDB`
`Influxd[Bb]`	`InfluxDB`
`Once`	`After`
`Pagerduty`	`PagerDuty`
`RCA Workbench`	`RCA workbench`
`Rudderstack`	`RudderStack`
`VMWare`	`VMware`
`Vmware`	`VMware`
`[Ww]orld [Ww]ide [Ww]eb`	`web`
`[cC]entos`	`CentOS`
`\b(?:[aA]daptive metrics\|adaptive Metrics)\b`	`Adaptive Metrics`
`ad[- ]?hoc`	`free-form\|user-written`
`back[ -]end`	`backend`
`blacklist`	`blocklist`
`blacklisted`	`blocklisted`
`blacklisting`	`blocklisting`
`blacklists`	`blocklists`
`cadvisor`	`cAdvisor`
`check[- ]box`	`checkbox`
`content type`	`media type`
`data-?source`	`data source`
`data-?sources`	`data sources`
`data[- ]?set`	`dataset`
`data[- ]?sets`	`datasets`
`datacenter`	`data center`
`datacenters`	`data centers`
`de-duplicate`	`deduplicate`
`de-duplicated`	`deduplicated`
`de-duplicates`	`deduplicates`
`de-duplication`	`deduplication`
`fewer data`	`less data`
`figma`	`Figma`
`file name`	`filename`
`file names`	`filenames`
`firewalls`	`firewall rules`
`front[ -]end`	`frontend`
`front[ -]ends`	`frontends`
`git`	`Git`
`grafana`	`Grafana`
`grayed-out`	`unavailable`
`gunicorn`	`Gunicorn`
`in order to`	`to`
`influx[Dd][Bb]`	`InfluxDB`
`jsonnet`	`Jsonnet`
`kotlin`	`Kotlin`
`langchain`	`LangChain`
`left[- ]hand[- ]side`	`left-side`
`log(?:ql\|QL)`	`LogQL`
`loki`	`Loki`
`lucene`	`Lucene`
`markdown`	`Markdown`
`memcached`	`Memcached`
`meta[- ]data`	`metadata`
`mix[- ]in`	`mixin`
`mysql`	`MySQL`
`network IP address`	`internal IP address`
`open-source`	`open source`
`otel`	`OTel`
`otlp`	`OTLP`
`pager[dD]uty`	`PagerDuty`
`phlare`	`Phlare`
`postgres`	`Postgres`
`postgresql`	`PostgreSQL`
`prom(?:ql\|QL)`	`PromQL`
`redis`	`Redis`
`regex[ep]?s`	`regular expression`
`regexp?`	`regular expression`
`repo`	`repository`
`repos`	`repositories`
`right[- ]hand[- ]side`	`right-side`
`rudderstack`	`RudderStack`
`sensu`	`Sensu`
`sign into`	`sign in to`
`sqlite`	`SQLite`
`style sheet`	`stylesheet`
`style sheets`	`stylesheet`
`synch`	`sync`
`synched`	`synced`
`synching`	`syncing`
`tempo`	`Tempo`
`the Grafana Agent`	`Grafana Agent`
`the RCA [Ww]orkbench`	`RCA workbench`
`threema`	`Threema`
`timeseries`	`time series\|time-series`
`trace(?:ql\|QL)`	`TraceQL`
`un(?:check\|select)`	`clear`
`url`	`URL`
`urls`	`URLs`
`vmware`	`VMware`
`vs\.`	`versus`
`webex`	`Webex`
`whitelist`	`allowlist`
`whitelisted`	`allowlisted`
`whitelisting`	`allowlisting`
`whitelists`	`allowlists`
`yugabyte`	`YugabyteDB`

More information ->

Suggestions

The following rules are suggestions to consider a certain point of style.

Grafana.Acronyms

Extends: conditional

Spell out <CURRENT TEXT>, if it’s unfamiliar to the audience.

More information ->

Grafana.Archives

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`[Uu]n(?:archive\|compress\|tar\|zip)`	`extract`
`[Zz][Ii][Pp](?: file)?`	`archive\|compressed file`
`unzip`	`extract`

More information ->

Grafana.DropDown

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Use drop-down as a modifier rather than as a standalone noun. For example: drop-down menu.

Current text	Replacement text
`drop ?down`	`drop-down`

More information ->

Grafana.GoogleContractions

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`are not`	`aren't`
`cannot`	`can't`
`could not`	`couldn't`
`did not`	`didn't`
`do not`	`don't`
`does not`	`doesn't`
`has not`	`hasn't`
`have not`	`haven't`
`how is`	`how's`
`is not`	`isn't`
`it is`	`it's`
`should not`	`shouldn't`
`that is`	`that's`
`they are`	`they're`
`was not`	`wasn't`
`we are`	`we're`
`we have`	`we've`
`were not`	`weren't`
`what is`	`what's`
`when is`	`when's`
`where is`	`where's`
`will not`	`won't`

More information ->

Grafana.GoogleOxfordComma

Extends: existence

Use the Oxford comma in <CURRENT TEXT>.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

(?:[^,]+,){1,}\s\w+\s(?:and|or)

More information ->

Grafana.GooglePassive

Extends: existence

In general, use active voice instead of passive voice (<CURRENT TEXT>).

<CURRENT TEXT> was matched by one or more of the following regular expressions:

[\w]+ed
awoken
beat
become
been
begun
bent
beset
bet
bid
bidden
bitten
bled
blown
born
bought
bound
bred
broadcast
broken
brought
built
burnt
burst
cast
caught
chosen
clung
come
cost
crept
cut
dealt
dived
done
drawn
dreamt
driven
drunk
dug
eaten
fallen
fed
felt
fit
fled
flown
flung
forbidden
foregone
forgiven
forgotten
forsaken
fought
found
frozen
given
gone
gotten
ground
grown
heard
held
hidden
hit
hung
hurt
kept
knelt
knit
known
laid
lain
leapt
learnt
led
left
lent
let
lighted
lost
made
meant
met
misspelt
mistaken
mown
overcome
overdone
overtaken
overthrown
paid
pled
proven
put
quit
read
rid
ridden
risen
run
rung
said
sat
sawn
seen
sent
set
sewn
shaken
shaven
shed
shod
shone
shorn
shot
shown
shrunk
shut
slain
slept
slid
slit
slung
smitten
sold
sought
sown
sped
spent
spilt
spit
split
spoken
spread
sprung
spun
stolen
stood
stridden
striven
struck
strung
stuck
stung
stunk
sung
sunk
swept
swollen
sworn
swum
swung
taken
taught
thought
thrived
thrown
thrust
told
torn
trodden
understood
upheld
upset
wed
wept
withheld
withstood
woken
won
worn
wound
woven
written
wrung

More information ->

Grafana.GoogleSemicolons

Extends: existence

Use semicolons judiciously.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

More information ->

Grafana.OAuth

Extends: substitution

Use <REPLACEMENT TEXT> instead of <CURRENT TEXT>.

Current text	Replacement text
`O[Aa]uth 2(?!\.0)`	`OAuth 2.0`
`O[Aa]uth(?! 2\.0)`	`OAuth 2.0`

More information ->

Grafana.Parentheses

Extends: existence

Use parentheses judiciously.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

$.{4,}$

More information ->

Grafana.ReadabilityAutomatedReadability

Extends: metric

<CURRENT TEXT> aim for below 8.

More information ->

Grafana.ReadabilityColemanLiau

Extends: metric

<CURRENT TEXT> aim for below 9.

More information ->

Grafana.ReadabilityFleschKincaid

Extends: metric

<CURRENT TEXT> aim for below 8.

More information ->

Grafana.ReadabilityFleschReadingEase

Extends: metric

<CURRENT TEXT> aim for above 70.

More information ->

Grafana.ReadabilityGunningFog

Extends: metric

<CURRENT TEXT> aim for below 10.

More information ->

Grafana.ReadabilityLIX

Extends: metric

<CURRENT TEXT> aim for below 35.

More information ->

Grafana.ReadabilitySMOG

Extends: metric

<CURRENT TEXT> aim for below 10.

More information ->

Grafana.Timeless

Extends: existence

Avoid using <CURRENT TEXT> 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.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

as of this writing
currently
does not yet
eventually
existing
future
in the future
latest
new
newer
now
old
older
presently
at present
soon

More information ->

Grafana.We

Extends: existence

Use first person plural pronouns like <CURRENT TEXT> 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.

<CURRENT TEXT> was matched by one or more of the following regular expressions:

we
we'(?:ve|re)
ours?
us
let's

More information ->

Grafana Labs' dictionary

Thu, 06 Jun 2024 12:17:39 +0100

Grafana Labs’ dictionary

The Grafana Labs documentation team maintains a dictionary used for spell checking. The same dictionary is used to generate some Vale rules from the metadata in the word definition.

The dictionary uses the Hunspell format generated from a Jsonnet template.

If a word doesn’t yet exist in the dictionary, you can add one by modifying the appropriate dictionary template file.

To add a new word to the dictionary, refer to Add words to the Grafana Labs dictionary.

Word metadata

Each word in the dictionary has metadata that describes it. The structure of that metadata is a Jsonnet object with the following fields:

Key	Value type	Description
`word`	`string`	The spelling of the word.
`affixes`	`string`	A concatenation of the letters corresponding to Hunspell affixes. For more information, refer to Hunspell affixes
`po`	`string`	The part of speech descriptor for the word. Known acceptable values include `'noun'`, `'adjective'`, and `'verb'`.
`description`	`string`	A description of the word.
`abbreviation`	`boolean`	If `true`, the word is an abbreviation. Defaults to `false`.
`established_abbreviation`	`boolean`	If `true`, the abbreviation doesn’t generally need explaining, like the abbreviation HTTP. Defaults to `false`
`product`	`boolean`	If `true`, the word is the name of any product, like Mimir or Facebook. Defaults to `false`.
`Amazon`	`boolean`	If `true`, the word is the name of an Amazon product, like Amazon CloudWatch. Defaults to `false`.
`Apache`	`boolean`	If `true`, the word is the name of an Apache project, like Apache Mesos. Defaults to `false`.
`Palantir`	`boolean`	If `true`, the word is the name of a Palantir product, like Apollo. Defaults to `false`.

You don’t create the object directly in the dictionary template file. Instead, you use the word.new function which prescribes the required fields.

To add new word, refer to Add words to the Grafana Labs dictionary.

To understand the Hunspell affixes, refer to Hunspell affixes.

Hunspell affixes

Hunspell affixes teach the dictionary multiple words by applying affix rules to the stem word. The affix rules are defined in en_US-grafana.aff.

Note
Affixes are case sensitive. d is a different affix to D

Letter	Kind	Description
`d`	Prefix	Adds the `de` prefix to the stem, making deprovision from provision.
`m`	Prefix	Adds the `mis` prefix to the stem, making misconfigure from configure.
`p`	Prefix	Adds the `pre` prefix to the stem, making preconfigure from configure.
`u`	Prefix	Adds the `un` prefix to the stem, making unregister from register.
`D`	Suffix	Adds the past tense suffix `ed` to the stem, making ingested from ingest.
`G`	Suffix	Adds the gerund suffix `ing` to the stem, making singing from sing.
`M`	Suffix	Adds the possessive suffix `'s` to the stem, making ingester’s from ingester.
`R`	Suffix	Adds the `r` suffix to the stem, making profiler from profile.
`S`	Suffix	Adds the plural suffix `s` to the stem, making namespaces from namespace.