Open source

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: Do not 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.
Reference structure

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

Reference template

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