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.

Annotated example of a concept page's structure

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.