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: Do not include steps or conceptual information in reference topics.
- 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.
index.mdfile within the reference directory.
Add front matter to the
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:
When you are ready to write, make a copy of the Reference template and add your content to it.