Topic types on Grafana Labs

Section page

Thu, 22 Aug 2024 00:00:00 +0000

Section page

Section pages, also called landing pages, direct users to the most valuable resources contained within the section.

Section structure

A section page includes the following elements:

Hero: A banner across the top of the page that includes the section title and a brief description.
Overview: A heading and one or two paragraphs that describe the resources contained within the section.
Explore: A heading that contains cards.
- Cards: Defined in the front matter, cards provide overviews of important pages and include links to those pages.

Write a section page

To write a section, follow these steps:

Determine where you want to add the section, or find an existing section page to update.
If you’re creating a new section, create a directory that follows this naming convention:
- The directory name matches the menu title planned for the section.
- Use lowercase letters.
- Add a hyphen between words.
Create an _index.md file within the section directory.
Add the usual front matter to the index file.

For more information about front matter, refer to Front matter.
Add the elements specific to a section page:
- Hero: A hero requires front matter and use of a shortcode.
- Cards: A card grid requires front matter and use of a shortcode.

Section page examples

Refer to the following pages for section page examples:

Grafana Explore: A section page without an image in the hero.
Alerts and IRM: A section page with an image in the hero.

Section template

When you’re ready to write, make a copy of the Section template and add your content.

Visualization topic

Thu, 21 Sep 2023 13:35:38 -0400

Visualization topic

A visualization topic provides an overview of a visualization type, its use cases, and the display options available in the user interface (UI). Visualization topics always include conceptual and reference content and may include task content.

The following types of content can be included in visualization topics:

A high-level overview of a visualization’s features, with use cases
Descriptions of the UI options unique to that visualization (common options are documented separately)
Screenshots that help users understand UI interactions or hard-to-describe UI
As needed, guidance on how to use the visualization in special use cases
Best practice guidelines

A visualization topic doesn’t include:

Tutorial content

Most visualizations require a data source; the ones that don’t are called widgets. As a result, a widget requires less documentation than a typical visualization. The structures for both of these are explained in the following sections:

Visualization topic structure

The following applies to visualizations that require a data source. For visualizations that don’t require one, refer to Widget topic structure.

A visualization topic includes the following elements. Optional sections are marked with an asterisk:

Topic title - A visualization topic title is the same as the name of the visualization as it’s written in the UI (for example, “Time series”). Don’t add the word “panel” or “visualization” to the title.
Introduction - Include an introduction that explains what the visualization type can help the user do.
Main visual - Add a clear screenshot depicting the visualization displaying a typical use case.
Body - The body can include task/how-to information as needed. The body includes the following sections:
- Configure a <VISUALIZATION>* - Link to a YouTube video describing a basic configuration example using the youtube shortcode.
- Grafana Play shortcode* - Use the docs/play shortcode to add links to representative examples of the visualization in Grafana Play. Place this shortcode after the main image or after a configuration video.
- Supported data formats - Provide guidance about which data formats are supported by the visualization type. Add examples, if needed.
- Special instructions or configuration options* - Add special configurations or instructions to achieve relevant tasks with the visualization. Each of these should have their own heading unless it makes sense to group some of them under a heading.
- Configuration options - This is a reference section for all of the configuration options for the visualization. Use the config-options-intro.md shared file to add intro text to this section. Nest the options under this heading.
  - <SECTION> options - For each expandable section of options in the panel editor pane, add a section in the topic with the name of the UI section, followed by the word “options”. For example, if a drop-down section of options is called “Axis” in the UI, include a heading in the topic called “Axis options”. List these sections in the order in which they appear in the UI.
    
    In sections with many configuration options, put them in a table and link to longer descriptions from the table. Use the provided shared files for the following options that are common to most visualization:
    - Data links
    - Field overrides
    - Legends
    - Panel options
    - Standard options
    - Thresholds
    - Tooltips
    - Value mappings
      
      If there’s more than one shared file for an option, use the one that’s an exact match to the UI of the particular visualization. If none are a match, manually document the options or create another shared file.

The following images show what the page-level TOC and (abridged) page might look like:

Widgets are visualizations that don’t require a data source. These visualizations have far fewer options and don’t need as much explanation. For visualizations that require a data source, refer to Visualization topic structure.

A widget topic includes the following elements:

Topic title - H1. A widget topic title is the same as the name of the widget as it’s written in the UI (for example, “Time series”). Don’t add the word “panel”, “visualization”, or “widget” to the title.
Introduction Include an introduction that explains what the visualization type can help the user do.
Main visual - Add a clear screenshot depicting the visualization displaying a typical use case.
Body - The body may include task/how-to information as needed. The body must include the following section:
- <SECTION> options - For each expandable section of options in the panel edit pane, add a section in the topic with the name of the UI section, followed by the word “options”. For example, if a drop-down section of options is called “Axis” in the UI, include a section in the topic called “Axis options”.

Naming conventions

When writing about visualizations or widgets use:

Noun form
Lower case, unless at the beginning of a sentence

For example:

Use bar charts to graph categorical data.
A bar chart lets you graph categorical data.

There are some cases where you should use the adjective form of a visualization. You should do this if:

The name of a visualization is already in plural form
It’s highly confusing because of other uses of the word
You’re referencing a visualization outside of the visualization documentation

Do this by adding the word “visualization”. For example:

Use time series visualizations to display time-series data as a graph.
A traces visualization turns traces data into a diagram.
Text visualizations allow you to directly include text or HTML in your dashboards.
Click the **Enable node graph** switch to display a node graph visualization above the trace view.

Write a visualization topic

To write a visualization or widget topic, follow these steps.

In the grafana/grafana repository, go to the docs/sources/panels-visualizations/visualizations directory.
In the visualizations directory, create a directory with the following naming convention:
- Use the name of the visualization type
- Use lowercase letters
- Add a hyphen between words
Within that directory, create an index.md file.
Copy the content of the Visualization template into your new index file.

For more information about the kinds of content you can add to a concept topic, refer to Visualization topic.
Add additional front matter to the index.md file.

For more information about front matter, refer to Front matter.

Visualization topic examples

Refer to the following topics for visualization topic examples:

Visualization template

When you’re ready to write, make a copy of the Visualization template and add your content.

Concept topic

Thu, 27 Oct 2022 16:43:50 -0400

Concept topic

A concept provides an overview and background information to help end users understand a product, interface, or task. Concepts answer the question “what is it?”. Readers learn about features through concepts.

The following types of content can be included in concepts:

Detailed overviews of features with benefits and clearly defined terms
Diagrams that help users understand the components of a system
Process flow diagrams
Best practice guidelines
An example of how a feature is used Examples might include screenshots or other supporting visuals

A concept topic doesn’t include:

Step-by-step instructions
Reference information, such as lookup tables or lists of values

Concept topic structure

A concept topic includes the following elements:

Topic title: Topic titles should be nouns, for example, Grafana panels. By using this naming convention, readers are able to distinguish between conceptual topics and tasks that begin with verbs. For best practice guidelines, use the title Best practices.
Introduction: Include an introduction that explains what this topic is about.
Body: Provide as much content as needed to explain the concept thoroughly. There can be sections, visuals, and text in the body of a concept.

Write a concept topic

To write a concept topic, follow these steps.

Determine where you want to add concept documentation to the Grafana Labs product documentation.
Within the top-level entity, create a parent directory with the following naming convention:
- Use a noun
- Use lowercase letters
- Add a hyphen between words
Within the parent directory, create an _index.md file.
Add front matter to the _index.md file.

For more information about front matter, refer to Front matter.
Add the content to a copy of the Concept template.

For more information about the kinds of content you can add to a concept topic, refer to Concept topic.

Concept topic examples

Refer to the following topics for concept topic examples:

Concept template

When you are ready to write, make a copy of the Concept template and add your content.

Reference topic

Thu, 27 Oct 2022 16:43:50 -0400

Reference topic

A reference topic provides users with the information they might need to refer to when performing a task. An effective reference provides a comprehensive list of data, such as functions and parameters, error messages, and return codes. A reference is usually presented as a table, a bulleted list, or a sample script.

API information is also included in reference topics.

Because reference topics contain information the user needs to accomplish a task, reference topics are often linked to task topics.

Note
Don’t include steps or conceptual information in reference topics.

Reference structure

Topic title: Reference topic titles contain a qualifier and noun, for example, Grafana CLI. This helps the reader distinguish between reference topics and tasks.
Introduction: Provide an introduction that explains what to expect from this topic.
Body: Use tables or lists to provide information within reference topics.

Write a reference topic

To write a reference, complete these steps:

Determine where you want to add reference documentation for a Grafana Labs product.
Create a child directory within the parent directory that follows this naming convention:
- Begin the directory name with a qualifier followed by an noun.
- Use lowercase letters.
- Add a hyphen between words.
Create an index.md file within the reference directory.
Add front matter to the index.md file.

For more information about front matter, refer to Front matter.
Make a copy of the Reference template, and add your content to it.

Reference topic examples

Refer to the following topics for a reference topic examples:

Reference template

When you are ready to write, make a copy of the Reference template and add your content to it.

Scenario topic

Thu, 27 Oct 2022 16:43:50 -0400

Scenario topic

A scenario shows how to apply product knowledge to solve a real problem in a realistic context. Scenarios help you make decisions, solve problems, and combine concepts and tasks to reach an outcome. Unlike a tutorial, a scenario doesn’t teach a single step-by-step procedure. It guides judgment and problem-solving in real situations.

Scenario structure

Use this structure to keep scenarios consistent across products while allowing flexibility for scope and narrative.

Topic title: Name the situation and goal. Use either a verb phrase or a noun phrase. For example, “Investigate a CPU spike during a deployment” or “CPU spike investigation during deployment.” Choose the form that best communicates the real-world context.
Overview: State the situation, the goal, and what the reader can do after completing the scenario. Highlight key decisions they’ll make. Example: “By the end, you can identify the source of a CPU spike and decide whether to scale or optimize.”
Before you begin: List prerequisites such as assumptions, access, roles, data available, and any baseline knowledge expected.
Approach (stages or decision points): Organize the body as a sequence of stages or micro-scenarios. For each stage:
- Context: What you observe and why it matters.
- Actions: What to try first. Link to tasks for steps and to concepts for background. Keep inline steps minimal.
- Decision: What to conclude or choose based on evidence.
- Principle (optional): The underlying takeaway or method you can apply to other problems, such as “begin with the alert signal, check dashboards for trends, and drill into logs or traces to confirm the root cause”.
Verify outcomes: Describe what “good” looks like and how to tell you’re done. For example, “p95 latency returns under target and the alert clears”.
Next steps: Link to related tutorials for learning and to tasks for implementation.

Audience and scope

Scenarios are for users who have completed onboarding and want to apply what they’ve learned to real environments. Assume readers have a functioning setup with access, permissions, and live data. Unlike tutorials, which use canned datasets, scenarios use the reader’s own data and context.

Scenario topics can vary in scope. You can write micro scenarios that focus on a single decision, such as “Alert fired: Is it noisy or real?”, or end-to-end scenarios that cover broader workflows, such as “Respond to a latency regression after a deploy”. Choose the smallest scope that produces a clear, transferable outcome.

Narrative and style

Follow these guidelines for narrative and style:

Use direct second person (“you”) and keep the voice instructional, not fictional. A light narrative frame is fine when it clarifies context, but avoid over-storytelling.
Focus on decisions, signals, and trade-offs. State the principle behind each step to help readers apply it in new situations.
Keep step lists short and link to tasks for detail. Keep explanations concise and link to concepts for depth.

Placement

Place scenarios under a Scenarios section within each product’s documentation, or near Learn content depending on your information architecture (IA).
Link scenarios from related concepts, tutorials, and tasks to create a clear learning path through the documentation.

Write a scenario topic

Follow these steps to write a scenario topic:

Choose a real situation users face, such as on-call, rollout, migration, optimization, or investigation.
Identify the few key principles and decisions that drive the path to resolution.
Draft the “Overview” and “Before you begin” sections to set expectations and assumptions.
Map 2-4 stages. In each, link to existing tasks and concepts instead of repeating steps.
Add “Verify outcomes” and “Next steps” to reinforce learning and help readers apply it to their own environment.

Difference between scenarios and other topic types

This table shows how scenarios differ from other content types:

Type	Purpose	Data & path	Reader outcome
Scenario	Apply knowledge to solve a realistic problem and practice judgment.	Often uses the reader’s own environment, has multiple valid paths, and provides links to tasks and concepts.	Reader can solve a similar problem and adapt the approach to their context.
Tutorial	Teach a defined skill through reproducible steps.	Uses controlled inputs and expected results in a linear path.	Reader can replicate the taught workflow.
Task	Complete a specific action with numbered steps.	Minimal context, single path.	Reader can perform the action once they’re in the right place.
Concept	Explain what something is and why it matters.	Explanatory only. No procedures.	Reader understands the idea and components.
Example / Use case	Show a common pattern, configuration, or system interaction, such as how alerting rules and dashboards work together.	Brief and abstract. May be non-procedural or focus on relationships rather than steps.	Reader recognizes when and where to apply a similar pattern in their own environment.

Tip
If you’re writing many steps with canned data and guaranteed outputs, write a tutorial. If you’re helping readers decide what to do with their own data to reach a goal, write a scenario.

Scenario template

Use this template to write a scenario:

# <SCENARIO_TITLE>

## Overview
You're <CONTEXT>. Your goal is to <GOAL>. By the end, you can <CAPABILITY_OR_OUTCOME>.

## Before you begin
- Access/roles:
- Data available:
- Baseline knowledge:

## Stage 1: <DECISION_OR_INVESTIGATION_STEP>
Context:  
Actions: (link tasks)  
Decision:  
Principle: (optional)

## Stage 2: <NEXT_STEP>
...

## Verify outcomes

You know you're done when <SIGNALS_OR_THRESHOLDS>.

## Variations and what-ifs
- If <CONDITION>, see <LINK>.
- If <CONDITION>, try <LINK>.

## Next steps
- <TASK_LINK>
- <CONCEPT_LINK>
- <TUTORIAL_LINK>

Use AI to write scenarios

You can use AI to speed up planning and drafting of scenarios.

When you prompt an AI tool:

Add context files such as your product docs, this scenario template, and the Grafana style guide.
Ask the AI to anonymize any transcripts and focus on the user’s goal, decisions, and outcomes.
Review the draft for accuracy and adjust the tone to match Grafana documentation.

For more example prompts and workflows, refer to the Docs AI Toolkit repository.

Examples

Task topic

Thu, 27 Oct 2022 16:43:50 -0400

Task topic

Task topics include numbered steps that describe how to achieve an outcome.

Task structure

A task topic includes the following elements:

Topic title: Write a task topic title that combines a verb and an object. The verb should describe the action completed by the task, for example, “Configure metrics-generator.” Refer to Headings and titles in the Google developer documentation style guide for more information.
Introduction: Provide an introduction that explains why the end user should care about the task.

There might be conceptual material in this section of a task topic. Limit conceptual information to only what’s relevant to the task at hand.

If you find yourself writing a long introduction, consider creating a concept topic, and then writing a shorter form of that concept in the task introduction. You can link to the longer concept topic from this introduction.
Before you begin: (optional) Add links to tasks that need to be completed before the current one. The links might sometimes be unrelated to the product, such as “Have this thing at hand”.

Additionally, this section can include decisions the user should make or permissions they need to confirm before starting the task.

If there are no prerequisites, don’t include this section.
Steps heading: Optional. The steps heading indicates that the steps are about to begin. Often follows “Before you begin” to delineate when the requirements end and the task starts. The steps heading may say “Steps” or a succinct description of a task.
Markdown
```
# Perform a task

...

## Before you begin

You need this stuff.
...

## Steps
```
In content that has multiple tasks in the same procedure, replace the Steps heading with a specific heading title that reflect what the user accomplishes in that section.
Markdown
```
# Set up alerts

...

## Before you begin

You need this stuff.
...

## Create a policy

...

## Set requirements for a policy
```
Stem sentence: The stem sentence introduces the steps.

Use the following convention when you write a stem sentence: To <NAME OF TASK>, follow these steps: For example: To create a dashboard, follow these steps:

For more information about stem sentences, refer to Procedures in the Google developer documentation style guide.
Steps: Users are provided with a directive through numbered steps.

Write steps so that they contain one action, or possibly two related actions, such as Copy and paste a value or Save and quit the program.

A step must instruct the reader to perform a specific task.

Write a task topic

To write a task, follow these steps:

Determine where you want to add task documentation to the Grafana Labs product documentation.
Create a child directory within the parent directory that follows this naming convention:
- The directory name should include a verb and an object.
- Use lowercase letters.
- Add a hyphen between words.
Create an index.md file within the task directory.
Add front matter to the index file.

For more information about front matter, refer to Front matter.
Add the content to a copy of the Task template.

Task topic examples

Refer to the following topics for task topic examples:

Task template

When you are ready to write, make a copy of the Task template and add your content.

When to combine tasks into a single topic

In some cases, task topics are standalone and don’t contain any other content. Other times, multiple task topics can be combined into a single Markdown file. By combining tasks into a single topic, the table of contents entities can be reduced in number, which reduces scrolling and clicking for users.

Note
It’s not a good idea to combine content in the same Markdown file at random. If you combine content incorrectly, you may inadvertently hide information from the user.

When combining multiple topics into one, follow these guidelines:

When you document more than one approach to accomplishing the same user goal.

In the Assign RBAC roles topic, a user can use the user interface or provisioning to assign roles. There is no need to create two task topic files in this case.
When tasks are likely to be completed around the same time.

Users might find it useful to have all task documentation available on the same page if they’re likely to complete a number of tasks simultaneously.

In the Data source management topic, it’s likely that an Admin user will enable permissions immediately after adding a data source.
When you document CRUD operations.

Create, read, update, and delete tasks can be combined into one topic. The Manage organizations topic includes tasks such as viewing, creating, editing, and deleting organizations all under the umbrella topic title of Manage.
When you document a user workflow.

Combine tasks when the user should start at the beginning, complete the first task, and then complete the remaining tasks in sequence.

In Activate a Grafana Enterprise license from AWS Marketplace on EKS, the user is guided through all the tasks necessary to activate their license.

Tutorial topic

Thu, 27 Oct 2022 16:43:50 -0400

Tutorial topic

The purpose of a tutorial is to show the reader how to “learn by doing” in a safe environment. A tutorial should build up quick successes. The length of a tutorial can vary from a few steps to many subtasks.

If you have an idea for a tutorial you’d like to develop, contact the Grafana Labs documentation team. Internal contributors can reach out on Slack and external contributors can send email to docs@grafana.com or reach out on the #docs channel on the Grafana Labs Community Slack.

Tutorial structure

A tutorial topic includes the following elements:

Topic title: Write a tutorial topic title that combines a verb and an object.
Overview: Let the user know the goal they will achieve by completing the tutorial. Provide context and include a list of the tasks the user will complete. Suggested text: “In this tutorial, you will …”.

There can be conceptual material in this section of a tutorial topic. However, limit conceptual information to only what’s relevant to the goal at hand.

If you find yourself writing a long introduction, consider creating a concept topic, and then writing a shorter form of that concept in the tutorial introduction. You can link to the concept topic from the tutorial.
Before you begin (optional): Describe or add links to tasks that a reader should complete before the tutorial. The links might sometimes be unrelated to the product, such as “Have this thing at hand.”

Additionally, this section can include decisions the user should make or permissions they need to confirm before starting the tutorial. Use a bulleted list if there is more than one prerequisite.

If there are no prerequisites, don’t include this section.
Task section (or sections): Create a section for each task needed to complete the tutorial. Follow the task guidelines to write the tasks.

To determine what tasks and steps you should include in your tutorial, perform a goal analysis and determine the valuable outcome the user wants to achieve. Limit the tutorial to the tasks needed to satisfy that goal. Work with a Subject Matter Expert (SME) to determine the goal and the minimal set of tasks. If possible, record the SME completing the tasks needed to accomplish the goal or ask the SME to record a demo of the tasks if that’s preferable.

Work with a Subject Matter Expert (SME) to:
- Provide steps that explain how to access or set up the data needed to complete the task. For more information, refer to Data for your tutorial.
- Don’t include written step numbers in the header, for example, “Step 1: Pick apples.”. Instead, include just the verb and object, for example “Pick apples.”
- Include only the tasks required for a straight path to the tutorial’s goal, not optional or alternative paths.
- Minimize the explanation within task steps. Instead, link to supporting explanations in related concept, task, and reference topics.
Summary (optional): Describe what the tutorial user has accomplished.
Next steps (optional): Provide logical next steps, if they exist.

Write a tutorial topic

To write a tutorial, complete these steps:

Add a docs/sources/tutorials directory to your project repository if one doesn’t yet exist.

The tutorial is committed alongside the other documentation in your repository, and after it’s published, it’s displayed on the Grafana Tutorials page. For more information, refer to Publish your tutorial.
Create a child directory within the tutorials directory that follows this naming convention:
- The directory name should include a verb and an object.
- Use lowercase letters.
- Add a hyphen between words.
Create an index.md file within the tutorial’s directory.
Add the content to a copy of the Tutorial template.
Add front matter to the index.md file.

For more information about front matter, refer to Front matter.

Tutorial template

When you are ready to write, make a copy of the Tutorial template and add your content.

Difference between tutorials and task topics

The difference between a tutorial and a task topic is that a tutorial is for learning, and a task is for actual operational work. Another important distinction is that a tutorial typically provides a “sandbox” environment—a source of data that users can safely experiment with.

Data for your tutorial

Depending on the application, your tutorial’s data might be:

In a sandbox
On test servers
In demo repositories that the user clones locally

For example, the Play with Grafana Mimir tutorial provides a repository that users can clone to complete the tutorial. In contrast, the Store exemplars in Grafana Mimir topic is a pure task that a user would follow to complete their work. For guidance on writing tasks, refer to Tasks.

If getting access to the tutorial data is complex, include the instructions in the steps of the tutorial. If getting access to the data is straightforward, include it in the “Before you begin” section.

Publish your tutorial

You store your tutorial source in your project repository in a docs/sources/tutorials directory and mounted to the tutorials repository so that it’s displayed on the Tutorials page. You store the source in your project repository for team members to review and edit the content.

The following sections describe how to hide the tutorial from your project’s table of contents and to display it on the Tutorials page.

Hide your tutorial from your table of contents

Tutorials are for learning, so it’s best to keep them together on the Tutorials page, accessible directly from the Grafana website’s Learn menu. As such, you need to hide the tutorial so that it doesn’t appear in your project’s table of contents.

Before you begin

Before completing these steps, you need to create a tutorials directory under docs/sources and add your tutorial into its own subdirectory as described in the Write a tutorial topic section.

To hide your tutorial from your documentation’s table of contents:

Open your project’s docs/sources/_index.md file.
Add the following YAML to the page’s front matter, replacing <PROJECT> with your project URL path.

If the cascade front matter already exists, you must merge this snippet with the existing front matter.

Note
Hugo cascade front matter can have two forms, array and mapping.

The following snippet uses the array form of the cascade front matter. If your front matter isn’t already in the array form, you will need to change it to that form.

For more information, refer to the cascade front matter documentation
YAML
```
cascade:
  - _target:
      path: /docs/<PROJECT>/*/tutorials/**
    _build:
      list: false
      render: false
```

Add your tutorial to the Tutorials page

Note
This procedure is for writers who have permissions to update the Grafana website repository.

To add your tutorial to the Tutorials page:

Add the following YAML to the manual_mounts field in the config/_default/params.yaml file in the website repository.

Replace <PROJECT> with your project name, <TUTORIAL> with the directory of your tutorial, and <VERSION> with the version of documentation you want to mount. Typically <VERSION> is either “next” or “latest”.
YAML
```
- source: content/docs/<PROJECT>/<VERSION>/tutorials/<TUTORIAL>
  target: content/tutorials/k8s-monitoring-app
```
Add the following YAML to the list field in the data/tutorials.yaml file in the website repository.

Replace <TUTORIAL> with the directory of your tutorial and <LEVEL> with one of “beginner”, “intermediate”, or “advanced” depending on the difficulty of your tutorial.
YAML
```
- page: /tutorials/<TUTORIAL>
  level: <LEVEL>
  type: tutorial
```

Tutorial topic examples

Refer to the following for tutorial examples: