1349629 - Create in-tree docs for the telemetry experiment annotation API

Status: RESOLVED FIXED

(Toolkit :: Telemetry, enhancement, P1)

Description

[Alessio Placitelli [:Dexter]]

Bug 1348748 adds a new API to annotate experiment data in the Telemetry Environment. The current documentation lives in the index page of the data collection docs [1]. We should create a new documentation page for it, with:

- the API documentation;
- usage example;
- any limit/constraint.

[1] - http://searchfox.org/mozilla-central/source/toolkit/components/telemetry/docs/collection/index.rst

Comment 1

[Alessio Placitelli [:Dexter]]

Attachment: Bug 1349629 - Create in-tree docs for the telemetry experiment annotation API.

Review commit: https://reviewboard.mozilla.org/r/129502/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/129502/

Comment 2

[Chris H-C :chutten]

Comment on attachment 8857535 [details]
Bug 1349629 - Create in-tree docs for the telemetry experiment annotation API.

https://reviewboard.mozilla.org/r/129502/#review132044

::: toolkit/components/telemetry/docs/collection/experiments.rst:4
(Diff revision 1)
> +=====================
> +Experiment Annotation
> +=====================
> +This API allows to annotate the :doc:`../data/environment` with any experiment a client is partecipating in, in a standard way.

This API allows whom to annotate the environment?

Also, s/partecipating/participating/.

Also, omit "in a standard way"

Also, plural "experiments" to highlight that we support multiple concurrent experiments.

::: toolkit/components/telemetry/docs/collection/experiments.rst:6
(Diff revision 1)
> +=====================
> +Experiment Annotation
> +=====================
> +This API allows to annotate the :doc:`../data/environment` with any experiment a client is partecipating in, in a standard way.
> +
> +The experiment annotation are sent with any ping including the `environment` data.

s/annotation/annotations/

"sent with any ping that includes the `environment` data"

(do we want to relinkify environment?)

::: toolkit/components/telemetry/docs/collection/experiments.rst:24
(Diff revision 1)
> +
> +.. code-block:: js
> +
> +    TelemetryEnvironment.setExperimentInactive(id)
> +
> +This synchronously returns a dictionary containing the informations for each active experiment.

Singular "information"

Comment 3

[Alessio Placitelli [:Dexter]]

Comment on attachment 8857535 [details]
Bug 1349629 - Create in-tree docs for the telemetry experiment annotation API.

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/129502/diff/1-2/

Comment 4

[Chris H-C :chutten]

Comment on attachment 8857535 [details]
Bug 1349629 - Create in-tree docs for the telemetry experiment annotation API.

https://reviewboard.mozilla.org/r/129502/#review132580

Comment 5

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/80f4a456ad1d
Create in-tree docs for the telemetry experiment annotation API. r=chutten

Comment 6

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

https://hg.mozilla.org/mozilla-central/rev/80f4a456ad1d