Word list
In most cases, you can refer to the word list in the Google developer documentation style guide to determine if you should use a word or not. The following guidelines cover cases in which:
- Grafana guidelines differ from Google guidelines.
- The word isn’t included in Google guidelines.
- The word is commonly used, generally or in other Grafana media.
Note
This page is a work in progress.
A
agentless
Don’t use. Grafana Agent has been replaced by Grafana Alloy, so you shouldn’t use agent-based terminology. Refer to no-collector.
alert rule
Grafana Alerting uses the term alert rule to describe the Grafana feature that includes both Grafana-managed alert rules and Data source-managed alert rules. For more information, refer to Alert rules.
Caution
Don’t confuse this with an alerting rule .
alerting rule
An alerting rule is a Prometheus concept reused in Grafana Mimir and Grafana Loki. For more information refer to Alerting Rules.
Caution
Don’t confuse this with an alert rule .
B
Best practices
Use the title Best practices for conceptual topics covering best practice guidelines.
C
CHANGELOG
When naming a file or making a general reference to CHANGELOGs, spell using all caps. When referencing a specific CHANGELOG file, match the same capitalization of that file.
D
data source
Use this rather than datasource for the noun form.
Also, use data source plugin rather than data-source plugin.
While most compound adjectives require a hyphen, it’s left out in this case to maintain consistency with the naming of data sources in the application and reduce confusion.
Note
For other compound adjectives, use a hyphen unless otherwise specified.
dataset
Use this rather than data set.
dialog box
Use this rather than modal or dialog.
This guidance intentionally differs from Google style guide advice, which prefers just dialog because dialog box is a user-friendly term.
drop-down
Use this rather than dropdown or drop down.
Use drop-down as a modifier rather than as a standalone noun. For example: drop-down menu.
E
easy
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.
end-to-end
Use this rather than e2e or E2E.
H
hover over
Use this rather than hold the pointer over or point to.
K
kebab case
Use this to refer to the naming convention where spaces between lower case words are replaced with dashes.
Use this instead of dash case.
M
menu icon
Use this rather than hamburger menu or kebab menu.
meta-monitoring
Use this instead of metamonitoring or meta monitoring.
N
no-collector
Use this to refer to deployments that don’t have a collector. Use this instead of agentless.
Node Exporter
When referring to the product, Prometheus Node Exporter, capitalize both words in the term Node Exporter. Don’t use Node exporter or node exporter.
When referring to the tool, use node_exporter.
The text should always be pre-formatted as inline code (between backticks (`)).
O
OK, okay
Avoid using OK or okay in technical documentation because it’s too informal. The exceptions are when you’re referencing or quoting:
- A user interface
- HTTP status codes or other code
Refer to the text formatting guidance for information on how to format these types of content.
Q
quickstart
Use the compound adjective without a hyphen whether the noun is implied or explicit. For example, you can use quickstart guide or just quickstart. If you’re using the noun form, write as two words.
R
React
Use this rather than React.js or ReactJS.
README
When naming a file or making a general reference to READMEs, spell using all caps. When referencing a specific README file, match the same capitalization of that file.
S
self-managed
Use self-managed instead of self-hosted, on-prem, or on-premise when talking about Grafana deployment methods.
This aligns with Marketing and various other parts of https://grafana.com.
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.
single pane of glass
This term should only be used in marketing materials. In technical documentation, use the following alternatives:
- single interface
- unified interface
SQL (Structured Query Language)
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.
T
time series
Use this rather than timeseries for the noun form.
When you need to use the adjective form, use time-series rather than timeseries.
