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.

     For example:

     • calculation-types
     • standard-field-definitions

3. Create an index.md file within the reference directory.

4. Add front matter to the index 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
• Standard field definitions
• Grafana CLI

Reference template

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