Skip to content

Creating new annotations

There are two recommended workflows for adding new annotations to this repository:

  1. Via the Metric's commentary section in the Glean Dictionary. This will either create a new markdown document for you to put information in or allow you to modify the existing one. When you're happy with your changes, convert your changes into a pull request.
  2. By directly adding a README.md (or a set of them) to the repository and making a pull request. Be sure to use the same application and metric identifiers as used in the Glean Dictionary, or your annotations will not be picked up. If you need help with this, feel free to ask.

Someone from the Data organization should review your pull request within a couple of days. After it is merged, your annotations should appear in the Glean Dictionary shortly thereafter.

At the moment, there are no strong guidelines on what content should be in an annotations file. Include whatever you think might be helpful to someone looking at a metric in the context of an analysis. Try to think about information that could save other people time when using the metric. Links to SQL queries or notebooks, tips for handling or interpreting missing data, or other difficulties you have encountered in handling the metric during analysis are some examples.

That said, there are a couple of points to bear in mind:

  1. The people reading your annotation will come from a diverse set of backgrounds: in language, culture, experience, and role as Mozillians. Avoid using flowery prose and unnecessary jargon. The guidelines for writing content for docs.telemetry.mozilla.org may be helpful reading.
  2. These annotations are in a public repository which is world readable. Avoid putting in partner-specific information which is under NDA, exact values or counts from our data (unless the source is an already-public dataset of dashboard) or anything otherwise sensitive. Generally speaking, information on how our software behaves is innocuous and fine to talk about, so don't over-rotate on this: talking about how we use data in public forums helps build trust with our community. It's ok to put in links to dashboards or other resources which are private (behind SSO), but please mark them as such (e.g. by putting (SSO) or the lock emoji 🔒 beside the link if not one of our automatically-linkified URLs, see below) and prefer public references where they exist.

Automatically linkified URLs

To save effort when writing annotations, we automatically create pretty URLs to sql.telemetry.mozilla.org. There is thus no need to use markdown link syntax with these types of urls: simply put in https://sql.telemetry.mozilla.org/queries/<query number> and the Glean Annotations machinery will take care of creating a pretty link (with a lock icon) for you.