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.
Write a concept topic
To write a concept topic, follow these steps.
Decide which top-level entity you want to add documentation to by reviewing 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.mdfile.Add front matter to the
_indexfile.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.