Open source

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.
  • 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.

  1. Determine where you want to add concept documentation to the Grafana Labs product documentation.

  2. 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
  3. Within the parent directory, create an file.

  4. Add front matter to the file.

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

  5. 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.