1432328 - Consolidate the documentation mechanism for telemetry

Status: NEW

(Firefox :: New Tab Page, enhancement, P3)

Description

[Ed Lee :Mardak]

From https://github.com/mozilla/activity-stream/issues/3616

The goal is to have a single source of truth for all the telemetry probes in AS.

Currently, AS has at least 3 sources regarding telemetry, doc/data_events.js&data_dictionary.js, test/schemas/pings.js, and the comments in the code base, respectively. Keeping them up-to-date and in sync is getting harder over time, and discrepancy will inadvertently sneak in as we're adding more probes to AS.

Some notes, findings, and caveats regarding certain metrics are also important, and should be recorded together with other documents. Unfortunately, they are mostly scattered in the source code comments or Github issues.

@dmose has mentioned some tools (joi-browser&sphinxjs) that might enable us to simplify this process, e.g. generating documents from Joi schema. We both believe that it's worth checking them out to see if they already meet our needs.

@dmose Feel free to add your thoughts here if I'm missing anything here :)