---
title: "Reference topic | Writers' Toolkit documentation"
description: "Learn how to write a reference topic."
---

# Reference topic

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
> 
> Don’t include steps or conceptual information in reference topics.

## Reference structure

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

[](/media/docs/writers-toolkit/reference.png)

## Write a reference topic

To write a reference, complete these steps:

1. Determine where you want to add reference documentation for a Grafana Labs product.
2. 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.
3. Create an `index.md` file within the reference directory.
4. Add front matter to the `index.md` file.
   
   For more information about front matter, refer to [Front matter](/docs/writers-toolkit/write/front-matter/).
5. Make a copy of the [Reference template](https://github.com/grafana/writers-toolkit/blob/main/docs/static/templates/reference-template.md), and add your content to it.

## Reference topic examples

Refer to the following topics for a reference topic examples:

- [Calculation types](/docs/grafana/latest/panels-visualizations/query-transform-data/calculation-types/)
- [Grafana CLI](/docs/grafana/latest/cli/)

## Reference template

When you are ready to write, make a copy of the [Reference template](https://github.com/grafana/writers-toolkit/blob/main/docs/static/templates/reference-template.md) and add your content to it.