Add documentation for tags

See: https://github.com/mozilla/glean_parser/pull/406

docs/user/SUMMARY.md

@@ -33,6 +33,7 @@
 - [YAML Registry Format](reference/yaml/index.md)
     - [Metrics](reference/yaml/metrics.md)
     - [Pings](reference/yaml/pings.md)
+    - [Tags](reference/yaml/tags.md)
 - [General API](reference/general/index.md)
     - [Initializing](reference/general/initializing.md)
     - [Toggling upload status](reference/general/toggling-upload-status.md)

docs/user/reference/yaml/tags.md

@@ -0,0 +1,51 @@
+# Tags YAML Registry Format
+
+Any number of custom "tags" can be added to any metric or ping.
+This can be useful in data discovery tools like the [Glean Dictionary](https://dictionary.telemetry.mozilla.org).
+The tags for an application are defined in YAML files which follow
+the [`tags.yaml` JSON schema](https://mozilla.github.io/glean_parser/tags-yaml.html).
+
+This files must be parsed by [`glean_parser`](https://pypi.org/project/glean-parser/) at build time in order to generate the metadata.
+
+For more information on how to introduce the `glean_parser` build step for a specific language /
+environment, refer to the ["Adding Glean to your project"](../../user/adding-glean-to-your-project/index.md)
+section of this book.
+
+{{#include ../../../shared/blockquote-info.html}}
+
+## Note on the naming of these files
+
+> Although we refer to pings definitions YAML files as `pings.yaml` throughout Glean documentation
+> this files may be named whatever makes the most sense for each project and may even be broken down
+> into multiple files, if necessary.
+
+## File structure
+
+```yaml
+---
+# Schema
+$schema: moz://mozilla.org/schemas/glean/tags/1-0-0
+
+Search:
+  description: Metrics or pings in the "search" domain
+```
+
+## Schema
+
+Declaring the schema at the top of a tags definitions file is required, as it is what indicates that the current file is a tag definitions file.
+
+## Name
+
+Tag names are the top-level keys on pings definitions files.
+One single definition file may contain multiple tag declarations.
+
+There is no restriction on the name of a tag, aside from the fact that they have a maximum of 80 characters.
+
+## Tag parameters
+
+### Required parameters
+
+#### `description`
+
+A textual description of the tag.
+It may contain [markdown syntax](https://www.markdownguide.org/basic-syntax/).

docs/user/user/metrics/adding-new-metrics.md

@@ -177,6 +177,9 @@ toolbar:
     type: event
     description: |
       Event to record toolbar clicks.
+    metadata:
+      tags:
+        - Interaction
     notification_emails:
       - CHANGE-ME@example.com
     bugs:

docs/user/user/pings/custom.md

@@ -18,6 +18,9 @@ $schema: moz://mozilla.org/schemas/glean/pings/2-0-0
 search:
   description: >
     A ping to record search data.
+  metadata:
+    tags:
+      - Search
   include_client_id: false
   notification_emails:
     - CHANGE-ME@example.com
@@ -27,6 +30,9 @@ search:
     - http://example.com/path/to/data-review
 ```
 
+Tags are an optional feature you can use to provide an additional layer of categorization to metrics.
+Any tags specified in the `metadata` section of a ping *must* have a corresponding entry in a [tags YAML registry](../../reference/yaml/tags.md) for your project.
+
 Refer to the [pings YAML registry format](../../reference/yaml/pings.md) for a full reference
 on the `pings.yaml` file structure.