Documentation structure
The Grafana Labs documentation team makes intentional decisions about how to organize and structure product documentation. The topic levels discussed on this page reflect common user goals. For example, a first-time Grafana user must understand the basic concepts before installing the product.
Before you begin contributing to documentation, it’s important to understand the structure of the content.
User goals and documentation structure
When writing documentation, focus on what your user’s goals are.
Use the structure of your documentation to reflect the user’s goals. Think about what your users want to do, what they need to know, and how they can accomplish the tasks.
This approach applies not only to content on a page but also to how you organize a set of documentation, whether it’s for a product or a feature.
With well-structured content, you can find what you need quickly and easily. Topics flow in a logical progression.
Structure of published content
Generally, documentation structure determines how content is:
- Titled
- Grouped
- Combined (or not combined) with other, related content
A standardized content structure that spans sets of documentation provides a consistent user experience. Information flows from a higher (less specific) level to a lower (more specific) level. For example, a new Grafana user wants to learn conceptual information first, so Introduction comes before Installation.
Use the topics you need
Depending on your product design and maturity, you may not need every topic:
- If a topic doesn’t apply to your project, you don’t need to use it.
- For Grafana OSS for example, you might use all of the headings.
- For Grafana Enterprise Traces for example, you might only use a subset of topics.
Some topics are optional and are usually found in specific contexts. For example, the Create and Monitor topics are used in Grafana OnCall, but aren’t used in Grafana Tempo.
Topic list
You can use the following high-level topics to group content. When writing new content, consider where it should appear given this content structure. For example, a conceptual page explaining metrics would go under the Introduction topic.
| Topic | Example link | Contents |
|---|---|---|
| Introduction | Introduction to Grafana | Conceptual, fundamental, or architectural information. |
| Get started | Get started with Tempo | Opinionated walk-throughs and tutorials. |
| Set up | Set up Grafana | System requirements, and subsections titled Set up, Configure, Upgrade, or Migrate. |
| Configure | Configure Grafana Agent | Configure can be its own section directory if the number of pages warrants it. Making this determination is not an exact science; use your best judgement. |
| Create alerts | Create a Grafana managed alert rule | Specific to Grafana Ops products (Alerting, OnCall, Incident, SLOs). The word alert may be changed, depending upon the product. If used with Grafana SLO, this then topic would be Create SLO. Do not use with backend database products, such as Tempo and Loki. Use Alerts instead, and refer to an operational product for details. |
| Manage alerts | Manage and monitor SLOs | Specific to Grafana Ops products (Alerting, OnCall, Incident, SLOs). Do not use with backend database products, such as Tempo and Loki. Use Alert instead, and refer to an operational product for details. |
| Integrate (with) [product] or Send data | Connect your data to Grafana Cloud | How to set up data integrations, product integrations, data sources, clients, plugins, and more. |
| Query data | TraceQL | Query languages, query tools, and examples. |
| Visualize data | Dashboards | Dashboard concepts and procedures. Link to the definitive source of dashboard documentation, rather than duplicating the information here. |
| Alert | Alerting and recording rules | This topic level is used for pages that discuss alerting features, like alerting rules in Grafana Loki. It provides a place for alerting content that’s not specific to the Grafana Operations products. |
| Manage [product] | Manage users and teams with Grafana OnCall | Information about managing a Grafana Labs product. For example, content in this topic helps you view, edit, and iterate on the Grafana product you installed. |
| Monitor [product] | Monitor Mimir | Information about using tools to monitor a Grafana Labs product. |
| References | HTTP API reference | APIs, configuration references, SDKs, and more. Material that is usually not procedural. |
Table of contents levels
The table of contents consists of the following section levels.
Top-level: A table of contents top-level represents groups of features and functions of a product. The first step in contributing to the documentation is to identify which top-level entity you will be contributing to.
Note
Don’t add a top-level entity to the table of contents. If you’re not sure where your documentation belongs, contact the technical documentation team.
Parent: Each top-level entity has one or more parents, which are groups of related feature content. Parent topics assist users in navigating to child topics.
Child: This level of the information architecture includes concepts, tasks, or reference topics.
Parent directory structure
Within the top-level directory, there is a parent directory.
The image below shows how the repository’s user-management parent directory is structured.
- There is an
_index.mdfile in the parent directory that serves as a landing page for the child topics. In most cases,_index.mdcontains conceptual content. For information about the types of conceptual content that you can add to the_index.mdfile, refer to Concepts. - There are also four task topics in the parent directory, each with a directory and
index.mdfile.
For more information about how to write concepts, refer to Concepts. For more information about how to write tasks, refer to Tasks.
Note
If a directory contains multiple pages or subdirectories, it’s a branch bundle, and it must include an_index.mdfile.
Pages and page bundles
Each web page generated by Hugo comes from one of three source files:
page/_index.md: a Hugo branch bundlepage/index.md: a Hugo leaf bundlepage.md: a Hugo page
Although each of the preceding examples results in the same URL (/page/), Hugo works with each source file differently.
Branch bundles (page/_index.md) produce page hierarchies.
For the /page/subpage/ URL to generated, there must first be a page/_index.md branch bundle source file.
Leaf bundles (page/index.md) bundle page assets.
To refer to a style sheet page/style.css with the link ./style.css, the link must be in a page/index.md leaf bundle source file.
You need to use leaf bundles if you intend to mount content from one part of the site to another using Hugo mounts.
Hugo mounts use a virtual filesystem before site generation, and you can only mount directories.
To mount the page /page/ to /other/page/, there must first be a page/index.md leaf bundle source file.
If you don’t know whether you need to mount a leaf bundle, you probably don’t and can default to using pages.
Pages (page.md) are any source files that aren’t leaf or branch bundles.
It’s convenient to use pages when you don’t require any of the behaviors of leaf or branch bundles, as it can be easier to distinguish two source files in some text editors or IDEs.
For more information about branch bundles and leaf bundles, refer to Page bundles.