Style guide on Grafana Labs

Style conventions

Mon, 27 Jun 2022 11:51:13 -0500

Style conventions

Consider this non-exhaustive list of technical writing techniques and styles when you write technical documentation. For questions you might have that aren’t addressed in these guidelines, refer to the Google developer documentation style guide.

Focus on user goals

Before you begin writing, clearly identify the goal of the user, and write content that supports the user reaching that goal.

Don’t document implementation details, specifications, or backend system operations that have no clear consequence to the user.
- Providing unnecessary information can lead to bloated content that forces the user to determine which content is relevant.
Avoid marketing clichés and hyperbole.
- Instead, use evidence-based or quantifiable language to focus and refine the information, and to offer value propositions.

Avoid mentioning other companies

Avoid mentioning other companies in technical documentation. Competitive content belongs in marketing materials.

There are some situations where you must mention another company, such as in data source plugin documentation or a migration guide. Otherwise, avoid doing so.

Don’t document third-party products

When documenting how our products integrate with partner products, document our usage of them, but don’t document the product itself.

Whenever possible, structure documentation so that you can link to the appropriate location in the third-party documentation.

Address users clearly

To address users clearly and directly, use second person (“you”) and avoid first person (“I”, “our”, or “we”). Use first person plural pronouns like ‘our’ carefully. Don’t use ‘we’ when you’re talking about the reader, instead use ‘you’. You can use ‘we’ when you’re talking about Grafana Labs.

Write directives in the imperative second person where the unspoken ‘you’ is implied.

Avoid making the user or their role, such as system administrator, the subject of a sentence, as in: “Users configure the Cloud using a secure shell.”.

Exception:

You can use first person in UI elements that are specific to the user, such as My profile or My account.

Use	Don’t use
Click Yes to accept the license agreement.	The license agreement is accepted when you click Yes.
To create a dashboard, add a panel and specify a data source.	To create a dashboard, you add a panel and specify a data source.

Write in active voice

When you write in active voice, you identify the subject of the sentence and the action that the subject performs. For example, “John drove the car” is active voice because it’s clear that John (the subject) performed an action (drove). The passive voice variation is “The car was driven by John.”

Use	Don’t use
After you create a dashboard, add a panel.	After the dashboard has been created, the panel can be added.
Click OK to save the dashboard configuration.	The dashboard configuration is saved when the OK button is clicked.

Write simple words, sentences, and paragraphs

Simple, direct communication is the key to effective technical communication.

Use short words whenever possible, such as “use,” not “utilize.”
- If possible, replace “use” and its variants (utilize, make use of) with a more descriptive verb.
Make your sentences shorter than 25 words.
- If you can remove a word without losing meaning, do so (typical culprits: there is; there are; in order to; it is important to; keep in mind).
- Consider writing shorter sentences or using a bulleted list if you find yourself writing long sentences.
Use simple verbs and tenses.
Consider the characteristics of your audience when choosing a term.
Don’t use buzzwords or jargon.
Keep paragraphs to three sentences or less.
- Condense the text, add more headings, or do both.
Use contractions in common and negative cases to express a conversational style: you’re, that’s, isn’t or _don’t_, for example.

Make content relevant to the user’s context. The more familiar you are with the user’s context, the better you can communicate without using a lot of words.

Write in present tense

When you write in present tense, avoid words such as have, has, had, been, should, would, and will.

However, similar to Google’s style guide, you can use future tense (will) when writing tutorials or to make it clear that an action that will occur in the future.

Use	Don’t use
The panel opens.	The panel will open.
The system prompts you to verify the deletion.	The system will prompt you to verify the deletion.
After you log in, your account begins the verification process.	After you log in, your account will then begin the verification process.
In this tutorial, you will:

Be positive

Write positive sentences instead of negative sentences. Positive sentences are easier for the user to understand and are usually shorter than negative sentences.

Use	Don’t use
The visualization updates with data after you click Apply.	The visualization won’t update with data until you click Apply.
Remember to involve your users in the dashboard creation process.	Don’t forget to involve your users in the dashboard creation process.

Write scannable content

Users often scan content rather than read. Long blocks of text minimize readability as they bury information.

Use the following techniques to make content easier to scan.

Write important information first.
Place actions before explanations.
Use short, bulleted lists.
Use headings to divide content.

Lists

For a discussion about lists and tables, refer to the Lists page in the Google developer documentation style guide.

Ordered lists

Ordered lists are also known as numbered lists.

For guidelines when writing numbered lists in Markdown, refer to Numbered lists.

Unordered lists

Refer to the following guidelines when you write unordered lists.

Begin list items with a capital letter unless there is a strong reason not to. For example, when you list case-sensitive parameters.
If they’re complete sentences, end list items with a period. If one item in a list ends with a period, then apply periods to all items in the list.

For more guidance, refer to Lists in the Google developer style guide.

Definition lists

Definition lists often used for providing a list of a term and indented definition. For example, you can use a definition list to document commands and their meanings:

Feature: Creates a feature
Features: Creates more than one feature; Sample additional features

To create a definition list, add the term on a new line then add a new line with a colon (:) along with the definition.

For additional information, refer to the Definition Lists from the Markdown Guide.

Sort lists

Sort lists and table rows alphabetically unless the order is important to understanding the information in the list or table.

Links and references

You should use refer to instead of see or check out when referencing another document.

Give the reader a sense of what to expect in the reference. Don’t use generic references, such as “Refer to [this file].”

As much as possible, use the exact title of the page or section you are linking to as the link text.

For example:

For more information about Grafana Labs products, refer to [Grafana documentation](/docs/grafana/latest/).

For more comprehensive guidance, refer to Write useful link text

Numbers

For direction on how to style numbers, follow the Google style guide except in the case of ordinals. An ordinal number is a number that indicates the position or order of something in relation to other numbers, like first, second, third, and so on.

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

Admonitions

To focus a user’s attention, Grafana Labs documentation includes notes, cautions, and warnings.

To standardize styling, each admonition has a special shortcode declaration. The following sections provide examples how to write each type. For the complete syntax reference, refer to Shortcodes.

Notes

A note provides additional information that the user should be aware of. Notes are the most common admonition.

The syntax for a note admonition is as follows:

{{< admonition type="note" >}}
This page describes a feature for Grafana 9.0 beta.
{{< /admonition >}}

On the published page, this note renders as follows:

Note
This page describes a feature for Grafana 9.0 beta.

Cautions

A caution warns the user to proceed with caution. A caution emphasizes a course of action’s potential downsides.

The syntax for a caution admonition is as follows:

{{< admonition type="caution" >}}
By disabling authentication requirements, anyone can access your Grafana instance.
There is a considerable security risk associated with this.
{{< /admonition >}}

On the published page, this caution renders as follows:

Caution
By disabling authentication requirements, anyone can access your Grafana instance. There is a considerable security risk associated with this.

Warnings

A warning informs the user not to do something. Warnings are reserved for actions that could cause harm to hardware, software, or data.

The syntax for a warning admonition is as follows:

{{< admonition type="warning" >}}
Don't back up your dashboards in Grafana.
You might not be able to recover a dashboard if it's deleted.
{{< /admonition >}}

On the published page, this warning renders as follows:

Warning
Don’t back up your dashboards in Grafana. You might not be able to recover a dashboard if it’s deleted.

Semantic line breaks

The Semantic Line Breaks organization suggests adding semantic line breaks in your writing . Adding a line break after each sentence makes it easier to understand the shape and structure of the source text

With line breaks:

When you write in active voice, you identify the subject of the sentence and the action that the subject performs.
For example, "John drove the car" is active voice because it is clear that John (the subject) performed an action (drove).
The passive voice variation is "The car was driven by John."

Without line breaks:

When you write in active voice, you identify the subject of the sentence and the action that the subject performs. For example, "John drove the car" is active voice because it is clear that John (the subject) performed an action (drove). The passive voice variation is "The car was driven by John."

The HTML output is the same in both cases. However, the first is easier to review and edit and is less subject to the screen and text editor settings of each contributor.

Text formatting

It’s a good idea to take a consistent approach to bold, italic, and other text formats.

Bold

Use bold formatting (**) when directly referring to UI elements.

When you’re referring to an abstract UI element, such as a role (Admin, Editor, Viewer), without directly referencing the UI, don’t bold the word. Capitalize the word and use it as an adjective, followed by the noun that it’s describing. For example:

Users with the Viewer role can't edit settings.

You can use bold inline with other prose in a table, but don’t use bold for the entire contents of a cell, even if it’s a UI element. For example:

Option	Description
Title	Text entered in this field appears at the top of your panel in the panel editor and in the dashboard. You can use variables you have defined in the Title field, but not global variables.

You can use bold for the first sentence in unordered lists that are followed by more information.

Thing: About the thing.

Use bold to indicate paths within a web application, and greater-than symbols (>) to indicate path separators. For example:

To add an administrator to the list of local users, navigate to **Appliance** > **Configuration** > **Access**.

Don’t use bold to draw attention to a word or phrase within a sentence, instead use italic emphasis.

Italic

Use italic formatting (_), to emphasize a specific word or phrase. This is particularly useful when defining a term for the first time.

For example:

The Prometheus data model is arranged into metrics that consist of a timestamp and a sample.

Code

Use code formatting (`) to refer to:

File names
Configuration options
User input
Code in text/inline text
Class and method names, status codes, and console output
Names of command line utilities

Voice and tone guidelines

Mon, 27 Jun 2022 11:51:13 -0500

Voice and tone guidelines

At Grafana, we like our company to sound like a real person.

Voice and tone reflect your attitude and how you convey information. Word choice, use of bold or italic emphasis, punctuation, and grammar all affect your voice. The tone you choose reflects the urgency of your message and can therefore change depending on the situation.

Consult the following voice and tone guidelines when you write technical documentation.

Project confidence

You know the subject matter better than anyone. Let your style reflect your expertise. Write in an authoritative tone to evoke confidence in your reader.

Be conversational

Write in a natural and conversational style with language that reflects a positive and friendly tone. Be informative and helpful by using easy-to-understand words and sentences. Keep your language simple and straightforward.

Tone

A casual tone is accepted in UI copy and supporting material compared to traditional business writing.

As long as they allow for shorter sentences, you can use the words and, but, and so in moderation.

Use contractions like isn’t for is not to help to convey an informal tone.

Task completion

Provide the user with just enough information to complete a task. Inform the user that something has happened as expected once the task is completed.

In headings for tasks, use a verb that clearly describes the action completed by the task. Avoid using gerunds in headings. For example, use “Configure metrics-generator” as a heading instead of “Configuring metrics-generator”.

Refer to Headings and titles in the Google developer documentation style guide for more information.

Learning

There are times when it’s helpful to explain or educate users more. It’s important to Grafana Labs that users feel confident about their actions and Grafana Labs’ product capabilities.

Don’t just teach people how to perform an action, but also why they should.

Motivation

Motivate the user to continue by providing information about the next steps. Don’t assume the user knows what the next steps are or what the outcome will be.

Capitalization and punctuation

Mon, 27 Jun 2022 11:51:13 -0500

Capitalization and punctuation

This section includes capitalization and punctuation guidelines.

Capitalization

Write headings in sentence case.

Refer to Headings and titles in the Google developer documentation style guide for more information.

Consult the following capitalization guidelines when you write.

Sentence case

Sentence case capitalizes the first word of a heading and all proper nouns.

This style is primarily lowercase and is considered the quickest form to read.

Capitalize abbreviations

Use all-caps capitalization for abbreviations, such as API, HTTP, ID, JSON, SQL, or URL.

For specialized abbreviations, spell out the first occurrence in a file and introduce the acronym in parentheses. You can then use the acronym through the remaining text.

Use rate, errors, and duration (RED) metrics derived from traces to investigate issues.

Capitalize proper nouns

The names of people, places, and products take initial capitals because they’re proper nouns.

If you’re not sure of whether something is a product or not, consult the product manager, or if there isn’t one, the responsible squad.

Grafana-specific capitalization guidelines

Menu and submenu titles always use sentence case: capitalize the first word, and lowercase the rest.
- Dashboards when referring to the submenu title.
- Keyboard shortcuts when referring to the submenu topic.
Generic and plural versions are always lowercase.
- Lowercase dashboard when referring to a dashboard generally.
- Lowercase dashboards when referring to multiple dashboards.
Exceptions: If a term is lowercase in the Grafana UI, then match the UI.
When you’re referring to an abstract UI element, such as a role (Admin, Editor, Viewer), without directly referencing the UI, don’t bold the word. Capitalize the word and use it as an adjective, followed by the noun that it’s describing. For example:
- Users with the Viewer role can’t edit settings.

Kubernetes objects

When referring to Kubernetes objects, such as Jobs, Pods, and StatefulSets, follow the guidance in the Kubernetes documentation style guide. Capitalizing objects makes it clear that you aren’t talking about generic jobs or deployments.

In the first use, introduce the object as Kubernetes XX, then use it alone in subsequent uses.

Examples:

Create the Kubernetes Job and check the logs to retrieve the generated token:
The Job requires the token

Amazon products

When referring to Amazon products such as Amazon CloudWatch, include the “Amazon” name prefix. After the first use, you can use just the product name.

In headings, always use the full name including “Amazon”.

Apache projects

When referring to Apache projects such as Apache Mesos, include the “Apache” name prefix. After the first use, you can use just the project name.

In headings, always use the full name including “Apache”.

Palantir products

When referring to Palantir products such as Palantir Apollo, include the “Palantir” name prefix. After the first use, you can use just the product name.

In headings, always use the full name including “Palantir”.

Google products

When referring to Google products such as Google Kubernetes Engine, include the “Google” name prefix. After the first use, you can use just the product name.

In headings, always use the full name including “Google”.

Punctuation guidelines

Refer to the following punctuation guidelines when you write technical content.

After a period, add one space, not two.
When listing a series of items, insert a comma before and or or. This is known as using serial commas or the Oxford comma.
- Example: “During lunch, they enjoyed quiche, quinoa, and kale salad.”
Don’t abbreviate and with an ampersand (&).
- Exception: If the UI uses an ampersand, match the UI.

Inclusive writing

Mon, 27 Jun 2022 11:51:13 -0500

Inclusive writing

When writing for Grafana Labs, always use inclusive terminology and phrasing. Avoid all statements that perpetuate gender, racial, or cultural stereotypes. Don’t use gendered words or demographically oriented terms that are irrelevant to the content.

Write about people

When writing about people, be compassionate, inclusive, and respectful.

No matter the context, we always make sure to view people as people. With that in mind, there are important distinctions between the ways that different people interact with our product and, thus, how we refer to those people.

Users are every person who uses our products, whether or not they use a commercial version of one of our products. Customers are people and companies who pay to use our products.
Visitors are people who visit our website for any reason, whether it’s as a potential user, customer, or employee. We appreciate all interest in our hard work.
Our customers (and users) often have their own customers (and users). Generally speaking, we refer to these customers of our customers as users.
Employees are people who work at Grafana Labs.

Best practices

Consider the following best practices to ensure inclusivity in your writing.

Group or audience: Don’t refer to a group or audience as it. Instead, use they.
Age: Don’t refer to someone’s age unless it’s relevant. Don’t use age-related words to describe people. Avoid: young, old, or elderly.
Hearing: Do use the adjectives deaf, partially deaf, or hard of hearing when describing a person with hearing loss.
Vision: Do use the adjective blind or low vision when describing a person with limited vision.

Write for an international audience

Grafana Labs uses US English as our standard for spelling, grammar, punctuation, and more. We write for an international audience with the following guidelines in mind:

Avoid acronyms

If you use an acronym, first write out each word in the acronym on first use, and then continue using just the acronym.

Example: Grafana Cloud is software as a service (SaaS). Using SaaS typically requires setting up an account.

Avoid idioms

Understanding idioms typically requires cultural context. Users of Grafana Labs products and projects are all around the world, and many are non-native English speakers. Therefore, avoid idioms and idiomatic puns.

For example, some common American English idioms:

Costs an arm and a leg
Hit the nail on the head
Bite off more than you can chew

Here are some more obscure British idioms:

A few sandwiches short of a picnic
Chuffed to bits
Over-egg the pudding

Avoid cultural references

Cultural references are references that relate to the culture of a community, country, continent, and so on.

Examples:

Her ambition is a clear reflection of the American dream.
You came to help like a good Samaritan.
They grew up in a typical nuclear family.

Avoid charged language

Avoid using charged language such as blacklist, master, and slave.

Allow, block

Avoid whitelist or blacklist.

When referring to allowing or blocking content or traffic, use a form of allow or block:

For the noun form, use allowlist or blocklist
For the verb form, use allow or block

Example: To allow outgoing traffic, add the IP to the allowlist.

Primary and secondary

Avoid master or slave.

Use the following approach to describe relationships between nodes or processes:

Use primary, main, or parent, instead of master.
Use secondary, replica, or child, instead of slave.

Right and left

Use the terms right and left with a qualifier like top or lower to help individuals with cognitive disabilities or those using screen-reading software.

Hyphenate when you’re modifying a noun. For example:

in the top-right corner
at the bottom left of the dialog box
the upper-left section
scroll toward the lower right

Don’t use the word hand as a qualifier like in right-hand corner.

Avoid directional language

Language that relies only on spatial direction doesn’t help users with visual disabilities or those who use screen readers. Remove directional language from your documentation when possible, and add language that doesn’t depend on spatial cues to help users navigate.

Use:

In the previous section
In the following table
The next step
Earlier in this topic

Don’t use:

In the section above
The table below
To the right
See the sidebar on the left

Write for developers

Mon, 27 Mar 2023 13:09:54 -0700

Write for developers

The guidelines that follow provide suggestions for writing documentation for software developers and engineers. Follow these tips to write useful API documentation, code examples, and other technical material. To learn how to communicate effectively with the developers who enhance and work with the code of Grafana Labs projects or products, read these guidelines in the context of the Style guide.

Developer documentation basics

Writing technical content for software developers is similar to writing content for users or administrators of software products, so the same general guidelines apply. However, developer-facing documentation tends to be more technical, and relies on certain important conventions. Because this type of documentation contains details about code, it’s important to know how to structure, format, and identify common problems that might arise.

When your readers are developers, you can assume that they’re familiar with general programming concepts. There is no need to explain elementary ideas. Instead, introduce those concepts and features that are specific to Grafana Labs products. For example, instead of covering the fundamentals of UI design in general, explain how Grafana Labs software or APIs interpret those principles.

Code comments

The foundation of strong documentation is well-written comments in code that are concise, relevant, and current.

For dos and don’ts of writing comments, refer to the Guidelines for code comments in grafana-\* packages.

For more general advice, consult one of the reputable Google Style Guides for your programming language.

Reference documentation

Whenever possible, automatically generate API and other reference documentation from source-code comments. However documentation is created, make sure it conforms to the style conventions. Pay particular attention to properly formatting the elements of code.

Auto-generated documentation

The advantages of automating documentation programmatically are well-known, and include increased consistency and a reduction in human-made errors. But behind every line of auto-generated content is a human author who is responsible for following the style guide.

When writing documentation used by an auto-generated program to create publishable content, keep the following things in mind:

An auto-generation tool can parse syntax, but when writing documentation used to create automated content, it’s up to you to add actionable insights.

What are the caveats, edge cases, and side effects?
What’s the bigger picture that’s not self-evident in the code?
In short, what’s everything that a developer needs to know to use the code?

Note
It might be difficult to integrate auto-generated content with other documentation, such as relevant sections of Get started guides, tutorials, or detailed code examples. You might need to ask a member of the Grafana Labs documentation team to ensure that your content is properly cross-referenced.

Elements of API references

Properly document the most common elements of an API reference, such as the title, parameters, return values, and so on. The following suggestions help you to write more complete and consistent documentation:

Element	Description
Title and description	The name of the element and a description of it in one or two sentences. Use backticks (``) for API names, classes, methods, and so forth, so they display in a fixed-width font.
Syntax	The code signature that defines the element. If it’s possible to use multiple programming languages, provide the syntax for each. Put the signature in `code font`.
Parameters	If the element has parameters, specify their descriptions, data types, and state whether they’re optional or required. If the parameters are optional, add the prefix “Optional:”. Put the parameters in italic.
Return values	If the element returns a value, describe the range of possibilities and the data type.
Error codes	Describe errors or exceptions and the conditions under which they occur. If possible, provide a way to resolve the issue.
Comments	Describe any important information that hasn’t been previously included in the title, description, syntax, parameters, or return values. For example, you might explain non-obvious context, make a comparison to similar elements, or provide cautionary notes about potential gotchas.

Additional tips:

Remember to write concisely. Don’t say “This method adds a user.” when you could “Adds a user.”. If your linter requires the description to begin with the element name, you may say “The AddUser method adds a user.” to avoid an error message.
When the names of code elements are singular, don’t make them plural. Instead, add a plural noun to describe them. For example, don’t change MyEvent to MyEvents; refer to the MyEvent objects.
If the element does some sort of action, start the first sentence of the description with an action verb.

Reference structure

Organize references alphabetically, organizing by frequency of use is too subjective.

If the reference has required and optional components, document them separately. Document the required components first, then the optional components. Organize each set of components alphabetically.

Code examples

Readers of documentation typically skim through it to find code samples they can copy and paste and run as is. Because of this and whenever possible, provide production-ready examples.

However, it isn’t necessary for every code example to be runnable in production. Some code examples are written to illustrate a point so that the developer can learn how to do something similar on their own. Such examples should be clearly marked as partial.

When providing an example, give a written description. You can put it either in the body of the document or as explanatory comments within the example code. However, don’t put comments in command line examples.

Remember the basic rule: explain why your code does what it does, rather than describe what it does. For an in-depth, external resource about writing developer documentation, refer to Docs for Developers.

Full code examples

To format code examples, use the following guidelines.

Highlight syntax

In Markdown, an info string after the first three backticks describes the language contained within. The website uses this information to apply syntax highlighting to code examples.

The following Markdown sets the info string to json:

```json
{ "key": "value" }
```

Some common languages and their info strings are:

Bash: bash
Console: console
Go: go
JSON: json
PromQL: promql
River: river
Shell: shell
YAML: yaml

Use appropriate whitespace for indentation

Spaces ( ) are a good default but note that some languages use alternative indentation. For example, Makefiles and Go source code uses tabs ( ) for indentation.

Use 2 spaces unless there is a clearly established alternative convention. For example, Python generally uses 4 spaces for indentation.

Above all else, be consistent with existing documentation in your area of the documentation or in your project.

Introduce each code sample with a sentence or paragraph to establish its context

End the introduction with a colon (:) if it immediately precedes the sample, or a period (.) if it doesn’t.

Use the `code` shortcode for tabbed examples

If you have the same example in multiple languages, use the code shortcode. The website presents the snippets in tabs and remembers the user’s preferred choice.

Partial code examples

Partial code examples are shorter and focus the reader on a specific area of the code. However, they require the user to integrate the partial code example with their existing configuration or other examples.

In addition to the general guidance for formatting code examples, when working with partial code examples, use the following guidelines.

Wherever possible, ensure the partial example is copy-pasteable

In JSON or YAML, the partial example should be valid on its own.

In programming language code examples, if the example won’t compile on its own, make sure the snippet is a recognizable unit of a source file.

Don’t use an ellipsis (…) or three periods (...) to omit information.

It breaks the readers ability to copy-paste the example and provides no additional context for the omission. Instead use the preceding sentences or valid code comments to clearly explain the scope of the example and what’s omitted.

For example:

The following YAML example demonstrates the configuration of a single port numbered 80 using the TCP protocol.

It’s part of a Kubernetes Service specification. It’s not a complete Service specification and you must incorporate it with the rest of a Service specification.
YAML
ports:
  - port: 80
    protocol: TCP

Explain how to integrate the example

With YAML examples especially, it’s important to explain how to integrate the example within a wide configuration.

Explain which key the example is the value for. The following example extends the one in the previous section:

The following YAML example demonstrates the configuration of a single port numbered 80 using the TCP protocol.

It’s part of a Kubernetes Service specification. It’s not a complete Service specification and you must incorporate it with the rest of a Service specification.

To incorporate the example, you must include it as the value to the Service spec mapping. If there is an existing ports value, you must choose to replace it or merge the two.
YAML
ports:
  - port: 80
    protocol: TCP

Refer to nested fields

With configuration in JSON or YAML, you may need to refer to deeply nested fields. Using natural language is laborious to write and read.

Instead use dot notation to separate nested fields. For example, spec.template.metadata to refer to the metadata field within the template field, which is itself within the spec field.

If the field name has dots, surround the name with square brackets instead. For example, spec.selector[app.kubernetes.io/name].

To refer to any member of an array, use [*].

To refer to a specific index in an array, use [<INDEX>]. For example, the following dot notation refers to the first container within spec, and the first port within that container: spec.containers[0].ports[0].containerPort.

The use of dot notation for nested fields is common in other engineering documentation such as Kubernetes documentation.

Paths, filenames, and URLs

Many types of information belong in fixed-width font. Among these are paths, filenames, directories, and folders. However, don’t format domain names or URLs as code if you intend the user to follow the link.

Command lines

Use the following conventions when you include commands on the command line in technical content.

Don’t assume everyone is using Linux. Make sure instructions include enough information for Windows and Mac users to successfully complete procedures.
Don’t add $ before commands so users can copy and paste them.
- Right: sudo yum install grafana
- Wrong: $ sudo yum install grafana
Include sudo before commands that require sudo to work.

For terminal examples and configurations, use a bash code block. In raw Markdown:

```bash
sudo yum install grafana
```

It produces:

sudo yum install grafana

If your command-line instructions include a combination of input and output lines, use separate code blocks for input and output, and use a console code block for the output.

The input, in raw Markdown:

```bash
cat ~/.ssh/my-ssh-key.pub
```

It produces the following output:

cat ~/.ssh/my-ssh-key.pub

For HTTP request/response, use an http code block in raw Markdown:

```http
GET /api/dashboards/id/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

It produces:

GET /api/dashboards/id/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

If an argument is optional, enclose it in square brackets. For required arguments, refer to Placeholder variables. For example, prefer the following raw Markdown:

```bash
ssh-rsa <KEY_VALUE> <USERNAME> [FILENAME]
```

It produces:

ssh-rsa <KEY_VALUE> <USERNAME> [FILENAME]

Placeholder variables

Use descriptive words and phrases when including placeholders, and avoid using X or XXX. In Markdown, in front of a placeholder, use an underscore (_) followed by a backtick (`) and a less-than sign (<). At the end of the placeholder, use a greater-than sign (>) followed by a backtick (`) and an underscore (_).

For example, refer to the following raw Markdown:

The following text is a placeholder: _`<PLACEHOLDER>`_.

It produces:

The following text is a placeholder: <PLACEHOLDER>.

For more information about formatting command lines, refer to Document command-line syntax from Google.

UX writing

Mon, 09 Jan 2023 09:14:32 -0500

UX writing

These guidelines provide guidance on creating text, style, and tone in the different components that make up the UI. They help you build UIs that enhance the user experience, are easy to use, consistent, and inclusive. These guidelines focus on UX writing. For more details on UI elements, refer to the Grafana Storybook React component library.

Tips for writing UI text

The following are tips for writing clear and concise UX microcopy.

Use a voice that’s friendly and not too formal

Be conversational but don’t use the voice you use when texting a friend.

Talk to users like you’re an engineer casually talking to other engineers.
Sound human and show empathy. Grafana projects are tools to help people complete their work and resolve issues.
Refrain from using “please” in your UI text.

Use:

We’ll guide you through the process of creating your SLOs.

Don’t use:

Here is a guide to set up SLOs.

Be clear and concise

The more words you use, the more time you waste.

Communicate only essential details.
Take time to edit what you write to make every word count.

Use:

Save changes

Don’t use:

Would you like to save your changes?

Address users in second person

Use “you” or “your” as though the UI is speaking to the users. Don’t use “please,” though.

Use:

Set the target for your SLO.

Don’t use:

The target can be set for an SLO.

Use:

Refer to Introduction to Kubernetes Monitoring for details.

Don’t use:

Please refer to Introduction to Kubernetes Monitoring for details.

Use active voice

Use active voice to make clear who is performing the action.

Use:

The server receives the query.

Don’t use:

The query is received by the server.

Use sentence case in UI elements

Capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns (people, places, products).

Note
If you’re not sure of whether something is a product or not, consult the product manager, or if there isn’t one, the responsible squad.

Use:

Create and manage dashboards to visualize your data.

Don’t use:

Create and Manage Dashboards to Visualize Your Data.

Use:

TLS/SSL root certificate

Don’t use:

TLS/SSL Root Certificate

Names of products from other companies

When using names of products from other companies, or referring to third-party product names, always follow that brand’s naming and usage.

Use:

Azure OpenAI Service

Don’t use:

Azure OpenAI service

Avoid words created for UI features

Avoid using UI terms when possible.

Use:

In your Grafana Cloud stack, click Connections.

Don’t use:

In your Grafana Cloud stack, click the Connections button.

Use numerals

The guideline for writing numbers in most mediums is to spell out the numbers one through nine. When writing UI text, it’s best to use numerals (1-9) because they’re easier to parse.

Use:

You have 3 messages.

Don’t use:

You have three messages.

Skip unnecessary punctuation

Avoid using periods for single sentences in UI elements.

Use:

Search by data source

Don’t use:

Search by data source.

Don’t use colons after labels.

Use:

Search by type

Don’t use:

Search by type:

Use periods for multiple sentences.

Use:

Metrics, Logs, and Traces are billed based on ingestion. For Metrics, we bill based on the number of active series using the ninety-fifth percentile during the period.

Don’t use:

Metrics, Logs, and Traces are billed based on ingestion
For Metrics, we bill based on the number of active series using the ninety-fifth percentile during the period.

Write scannable descriptive text

Using long blocks of descriptive text reduces readability. Write important information first and use short, bulleted lists. Use headings to divide content.

Use:

Before you begin, make sure you have the following items:

The kubectl command-line tool. To learn how to install kubectl, refer to kubectl.

(Optional) The helm command-line tool for managing Helm charts. To learn how to install helm, refer to Installing Helm in the Helm documentation.

Don’t use:

Before you begin, make sure you have the kubectl command-line tool available on your local machine. To learn how to install kubectl, refer to kubectl in the Kubernetes documentation. You might also need the helm command-line tool for managing Helm charts. To learn how to install helm, refer to Installing Helm from the Helm documentation.

Write text for UI elements

The following sections provide writing guidelines for common UI elements:

Buttons
Input fields and validation
Errors
Alert modals
Confirm modals
Tooltips
Headings
Links

If you’d like Grafana Labs to add a UI element, refer to the template at the bottom of this topic.

Buttons

Use buttons when you want users to take actions, such as adding or creating new records or types of information in an existing system.

Start button labels with a verb.
Aim for using one to two words, with a maximum of four words.
Make button labels descriptive, and tell the user what action occurs if they click it.

Rather than using OK or Cancel, be specific. For example, use Save / Don’t save rather than Save / Cancel.
Use sentence case without punctuation. For example, use Save changes rather than Save Changes.

Common use cases for buttons

Button	When to use it	Examples
Create	Use when you’re creating something new, from scratch or from within an existing app. Creating can involve building something (often large) from scratch.	Create Create incident Create entry
Add	Use when you’re adding something into a larger thing. Add extra details to an existing thing. Adding is usually a small or single step, with less work than creating.	Add details Add contact
Save	Save something to a server.	Save Save and exit Save changes
Edit	Change or update something that already exists. This doesn’t affect the server until the user saves.	Edit
Preview	Preview a runtime version of whatever you are working on. This action doesn’t take you away from or override the page you’re already on.	Preview
Cancel	Cancel or leave a process. Leave without saving any changes. Although Cancel is a common button name, it’s better to be specific and name the action that’s being cancelled.	Cancel
Close	Close a window.	Close
Delete	Permanently delete something from the server. This usually prompts a confirmation dialog box, asking you to confirm your decision.	Delete notification policy Deleting this notification policy permanently removes it. Are you sure you want to delete this policy? Yes, delete
Remove	Remove an item from a list.	Remove

Refer to the Grafana Storybook React component library for button usage and an example.

Input fields

Use short and scannable text for input field labels. Use sentence case and front-load your field labels with terms that most clearly describe the values they need to enter in the input field.

If you provide instructions for an input field, be clear about limitations, requirements, and available characters for that field. Use a red asterisk for required fields. Use sentence case without punctuation for the instructions, unless there are multiple sentences.

Optionally, you can provide descriptive placeholder text in an input field. If you do so, make your description clear and concise. The placeholder text should be a hint of the value to be expected.

Refer to the Grafana Storybook React component library for button usage and an example.

Errors

Make errors visible to users, helpful, and easy to understand. Error messages tell the user what happened and what they can do to fix the error.

The error headline includes a concise, meaningful summary of the error. Error details provide as much information as possible.
Include reasons and instructions for fixing the issue, if possible. Don’t give just the system logs or error titles. Try to state how the error was caused and what the user can do to fix it. Assume that some of your users might not understand crash logs and need a simpler description.
Write error messages for humans without blame. Don’t use over-dramatic wording or jargon, and avoid apologies. Give a no-nonsense summary of what went wrong and include the degree of severity, in understandable terms.
Like other UI elements, use sentence case, plain language, and active voice in both the title and details. Don’t use the term “invalid” in an error message. Instead use “not valid” if necessary.

Refer also to Alert modals.

Use:

Failed to evaluate queries and expressions: Add a query target to alert rule.

Don’t use:

Failed to evaluate queries and expressions: [plugin.downstreamError] failed to query data: no query target found for the alert rule.

Use:

Complete the required fields marked by *.

Don’t use:

It looks like you missed a required field.

Use:

The server is unresponsive.

Don’t use:

Oops, the server appears to be on a break.

Refer to the Grafana Storybook React component library for input field usage and an example.

Input field validation

Use an input field validation when a text field has formatting requirements. If the validation fails, show the error message directly below the field.

Refer to the Grafana Storybook React component library for an example of an input field with validation.

Alert modals

An alert modal displays an important message in a way that attracts the user’s attention without interrupting the user’s task.

Assume that some of your users might not understand technical terms and need simple, clear alert messages. Like other UI elements, use sentence case, plain language, and active voice in alerts.

Note
The word “modal” is considered jargon and you shouldn’t use it when writing documentation, except for developer documentation of code referencing a modal. Use “dialog box” instead.

Severity levels

Alert modals have severity levels (error, warning, info, and success) with different colors used for each level:

Severity	When to use
	Use an error if an action fails and the user is prevented from completing their task.
	Use a warning to say “don’t do this,” for example, if the step might be irreversible, leading to permanent data loss.
	Use as a note to provide useful but not critical information.
	Use to indicate that an action has completed without errors.

Actionable instructions

For error messages, provide actionable instructions to help users complete their task successfully.

Use:

Warning

You’ll need additional permissions to perform this action.

Permissions needed: plugins:write

Don’t use:

Error

You’ll need additional permissions to perform this action.

Confirm modals

Use confirm modals to request the user to confirm an action, for example, a deletion. Confirm modals interrupt the user in their flow and force them to deal with the action in the modal. Only use a modal if this interruption is a good thing, for example, when the cost of an error is high.

Use affirmative actions with verbs in confirmation messages. Direct and actionable language encourages the user to take the next step.
Be sure to also explain the impact and consequences of the options that the user can take. Like other UI elements, use sentence case, plain language, and active voice in the confirmation message title and details.

Use:

Use Google’s location service?

Let Google help apps determine location. This means sending anonymous location data to Google, even when no apps are running.

Don’t use:

Are you sure?

Refer to the Grafana Storybook React component library for confirm modal usage and an example.

Tooltips

Use tooltips to identify UI objects, such as icons. Users hover over a UI object to view a box with a description.

Use tooltips for ancillary information since users only refer to the information if they hover over the object.
Keep tooltips brief, generally fewer than 120 characters.
Consider using tooltips for additional in-app documentation as in this example:

Refer to the Grafana Storybook React component library for tooltip modal usage and an example.

Headings

A heading gives structure to your UI elements. Use headings whenever you need to break your content down into hierarchical chunks, often in windows, dialog boxes, and wizards.

Headings are specific and meaningful and include the most relevant keywords and main points of the chunk, while staying short.
For headings, use sentence case without punctuation except for question marks when needed. Front-load your headings by putting the word people are looking for at the front of your headline.

Use:

Connect your data to Grafana Cloud

Don’t use:

Connect Your Data to Grafana Cloud

Links

If your product is complex, you might be unable to provide relevant details concisely in the UI text. In this case, you can provide links to documentation for details.

Use links sparingly. Try first to write concise and complete UI text. If you include a link, make sure the referenced content helps the user with the task they’re completing in the UI.
Your link text should be descriptive, telling the user what content they will find upon clicking. Use the exact title of the topic they’re linking to so that if the link breaks, they can search for the topic. Like headings, front-load the link text by putting the word people are looking for at the front of your link.
Include the link either at the beginning or end of a sentence, not in the middle. Don’t include preceding articles as part of the linked text.
For overview text, you can link to relevant overview documentation and Grafana University courses.

Use

Get started

Create an alert rule by adding queries and expressions from multiple data sources:

Add labels to your alert rules to connect them to notification policies.

Configure contact points to define where to send your notifications to.

Configure notification policies to route your alert instances to contact points.

Read an overview in the documentation >

Learn more in the Grafana University course >

Additional elements

The UI elements described here aren’t exhaustive. If you’d like specific types of UI elements added, let Grafana Labs know. Internal contributors can reach out on Slack and external contributors can email docs@grafana.com.

Use the following template to provide input.

Template

Use this template to add guidelines for UI elements.

Write an introduction about the element. Say what its intent or purpose is in an experience.

Provide writing guidelines for the element.

Provide links to usage and examples of the element in the Grafana Storybook React component library.

Use

Provide an example of how to use the element.

Don’t use

Provide an example of how not to use the element.

Word list

Thu, 21 Sep 2023 15:26:25 -0400

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

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.

UI elements list

Wed, 27 Sep 2023 17:05:44 -0400

UI elements list

This list provides guidance for how to refer to user interface (UI) elements in Grafana.

Note
To view the images in this table, click Expand Table at the top-right corner of the table.

UI element	Description	Notes
breadcrumb	The area at the top of the screen that displays your location in the application and allows you to navigate between the displayed locations.	Don’t refer to this as the navigation bar, top navigation, or header except in the case of the dashboard header (see below).
dashboard header	The area at the top of the screen that displays your location in the application and includes dashboard tools.
dialog box	A box that appears on top of the main screen of the application where you can enter information or select commands.	Don’t use modal or dialog without box.
drawer	A pane that slides out from the right side of the screen.	Don’t use panel, pop-up, or view.
main menu	The navigation that opens on the left side of the screen when you click the logo in top-left corner.	Don’t refer to this as the navigation menu or primary menu.
menu icon	The element that opens a menu.	Don’t refer to this as the hamburger menu.
panel header	The area at the of a panel that contains the panel name, the edit menu, and other indicators.
switch	Used to turn UI features on and off.	Don’t refer to this as a toggle.
tab	An element that lets multiple pages exist within one screen.	Other UI elements, such as radio button groups (example 1, example 2), behave much like tabs, but shouldn’t be referred to as tabs; avoid naming these elements, using just the element label instead.

AI quick reference

Thu, 24 Sep 2026 19:16:43 +0000

AI quick reference

This page is a concise reference for AI agents writing or reviewing Grafana documentation. It summarizes the style guide and the Google developer documentation style guide. If a rule isn’t here or a case is ambiguous, refer to the full page before you guess.

Ground every claim

Back every claim about product behavior, defaults, UI, or permissions with a source file or page. If you can’t verify a claim, mark it [UNVERIFIED] rather than guessing.

Audience

Write for Grafana Labs users, not staff.
Don’t document how to develop on the project.
Don’t document deployment for Grafana Cloud products.

Product names

Use long product names with “Grafana” in overviews; use short names without “Grafana” in the body.
Always write “Grafana Cloud,” never just “Cloud.”
List signal types in this order: metrics, logs, traces, profiles.

Voice and tone

Write in second person, active voice, and present tense.
Use contractions: “isn’t”, “don’t”, “you’re.”

Be confident, not boastful. Avoid “easy”, “simple”, “just”, and marketing clichés.

Prefer positive framing over negative.
Follow “Every Page is Page One”: each page stands on its own.
Define or plainly describe a term before you use it; don’t assume the reader knows Grafana jargon.

Sentences and paragraphs

Prefer short sentences and paragraphs.

Cut filler: “there is”, “there are”, “in order to”, “it is important to.”

Don’t use lists as a substitute for paragraphs.

Capitalization and punctuation

Use sentence case for titles, headings, and UI element references.
Use the serial (Oxford) comma: “metrics, logs, and traces.”
Don’t abbreviate “and” with “&” unless matching the UI.

Headings

Start task headings with a verb. Don’t use “Step X:” in headings.
Don’t start headings with a gerund.
Include a short introduction after each heading.
Structure most content under h2 headings; use h3 for related subsections.

UI elements

Bold the label text, not the element type: “Click Apply”, not “click the Apply button.”
Match UI casing exactly.
Write navigation paths with >: “Go to Alerting > Notification policies.”
Capitalize roles as adjectives; don’t bold them.
Use code formatting for filenames, configuration options, CLI commands, and status codes.

Word list and conventions

Follow Grafana preferred terms. For example, use “data source” (not “datasource”), “self-managed” (not “self-hosted”), and “allowlist”/“blocklist” (not “whitelist”/“blacklist”). For the full list, refer to Word list.

Use <VARIABLE_NAME> in code blocks and VARIABLE_NAME in prose.
Write for an international audience: avoid idioms and directional language such as “on the left.”

Security

Thu, 04 Dec 2025 14:00:01 +0000

Security

While there is no expectation that writers or engineers are security experts, we want to ensure that our documentation takes security into mind.

Invalid tokens

It is rarely necessary for documentation to include tokens that are or look valid. We prefer to mimic valid token formats, where we replace the majority of the tokens with text that makes them obviously invalid.

Examples of obviously invalid tokens would be:

Grafana Labs tokens: glsa_iNValIdinValiDinvalidinvalidinva_5b582697.
GitHub tokens: github_pat_XXXXXXXXXXXXXXXX.

Style guide on Grafana Labs

Style conventions

Style conventions

Focus on user goals

Avoid mentioning other companies

Don’t document third-party products

Address users clearly

Write in active voice

Write simple words, sentences, and paragraphs

Write in present tense

Be positive

Write scannable content

Lists

Ordered lists

Unordered lists

Definition lists

Sort lists

Links and references

Numbers

Admonitions

Notes

Cautions

Warnings

Semantic line breaks

Text formatting

Bold

Italic

Code

Voice and tone guidelines

Voice and tone guidelines

Project confidence

Be conversational

Tone

Task completion

Learning

Motivation

Capitalization and punctuation

Capitalization and punctuation

Capitalization

Sentence case

Capitalize abbreviations

Capitalize proper nouns

Grafana-specific capitalization guidelines

Kubernetes objects

Amazon products

Apache projects

Palantir products

Google products

Punctuation guidelines

Inclusive writing

Inclusive writing

Write about people

Best practices

Write for an international audience

Avoid acronyms

Avoid idioms

Avoid cultural references

Avoid charged language

Allow, block

Primary and secondary

Right and left

Avoid directional language

Write for developers

Write for developers

Developer documentation basics

Code comments

Reference documentation

Auto-generated documentation

Elements of API references

Reference structure

Code examples

Full code examples

Highlight syntax

Use appropriate whitespace for indentation

Introduce each code sample with a sentence or paragraph to establish its context

Use the code shortcode for tabbed examples

Partial code examples

Wherever possible, ensure the partial example is copy-pasteable

Explain how to integrate the example

Refer to nested fields

Use the `code` shortcode for tabbed examples