new file mode 100644
--- /dev/null
+++ b/toolkit/components/telemetry/docs/collection/experiments.rst
@@ -0,0 +1,38 @@
+=====================
+Experiment Annotation
+=====================
+This API allows privileged JavaScript to annotate the :doc:`../data/environment` with any experiments a client is participating in.
+
+The experiment annotations are sent with any ping that includes the :doc:`../data/environment` data.
+
+The JS API
+==========
+Privileged JavaScript code can annotate experiments using the functions exposed by ``TelemetryEnvironment.jsm``.
+
+The following function adds an annotation to the environment for the provided ``id`` and ``branch``. Calling this function repeatedly with the same ``id`` will overwrite the state and trigger new subsessions (subject to throttling).
+
+.. code-block:: js
+
+    TelemetryEnvironment.setExperimentActive(id, branch)
+
+This removes the annotation for the experiment with the provided ``id``.
+
+.. code-block:: js
+
+    TelemetryEnvironment.setExperimentInactive(id)
+
+This synchronously returns a dictionary containing the information for each active experiment.
+
+.. code-block:: js
+
+    TelemetryEnvironment.getActiveExperiments()
+
+.. note::
+
+    Both ``setExperimentActive`` and ``setExperimentInactive`` trigger a new subsession. However
+    the latter only does so if there was an active experiment with the provided ``id``.
+
+Limits and restrictions
+-----------------------
+To prevent abuses, the content of both the experiment ``id`` and ``branch`` is limited to
+100 characters in length.

--- a/toolkit/components/telemetry/docs/collection/index.rst
+++ b/toolkit/components/telemetry/docs/collection/index.rst
@@ -16,34 +16,28 @@ The current data collection possibilitie
 * :doc:`histograms` can efficiently record multiple data points
 * ``environment`` data records information about the system and settings a session occurs in
 * :doc:`events` can record richer data on individual occurences of specific actions
 * ``TelemetryLog`` allows collecting ordered event entries (note: this does not have supporting analysis tools)
 * :doc:`measuring elapsed time <measuring-time>`
 * :doc:`custom pings <custom-pings>`
 * :doc:`stack capture <stack-capture>` allow recording application call stacks
 * :doc:`Use counters <use-counters>` measure the usage of web platform features
+* :doc:`Experiment annotations <experiments>`
 
 .. toctree::
    :maxdepth: 2
    :titlesonly:
    :hidden:
    :glob:
 
    scalars
    histograms
    events
    measuring-time
    custom-pings
    stack-capture
+   experiments
    *
 
 Browser Usage Telemetry
 ~~~~~~~~~~~~~~~~~~~~~~~
 For more information, see :ref:`browserusagetelemetry`.
-
-Experiment Annotation
-~~~~~~~~~~~~~~~~~~~~~
-Experiment annotations can be added through the API exposed in ``TelemetryEnvironment.jsm`` and are collected in the :doc:`environment <../data/environment>`:
-
-- ``TelemetryEnvironment.setExperimentActive(id, branch)``, adds an annotation to the environment for the provided ``id`` and ``branch``. This triggers a new subsession.
-- ``TelemetryEnvironment.setExperimentInactive(id)``, removes the annotation for the experiment with the provided ``id``. This triggers a new subsession.
-- ``TelemetryEnvironment.getActiveExperiments()``, returns a dictionary containing the informations for each active experiment.