Documentation Writers' Toolkit Structure Topic types Reference

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.

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.

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.

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

• Calculation types
• Grafana CLI

Reference template

When you are ready to write, make a copy of the Reference template and add your content to it.