1496775 - Draft documentation about the central unified telemetry pings

Status: RESOLVED FIXED

(Toolkit :: Telemetry, enhancement, P1)

Description

[Chris H-C :chutten]

We have several pings that are central to our understanding of Firefox. While each have their own in-tree documentation, there is no central location to document which ones we consider central, and what factors affect their use, timing, and presence.

Draft a document about our central data-carrying pings and their behaviours, timelines, and timings.

Specifically:
main, first-shutdown, event, new-profile, update, crash, and opt-out

With particular attention paid to:
contents, scheduling, pingsender use, and relevant historical anecdotes

This will not cover Fennec, GeckoView, or future Mobile Telemetry SDK work.

Comment 1

[Chris H-C :chutten]

draft: https://docs.google.com/document/d/1MWvG2gLCSMFxE8mFQNao_w4mefk9Bg2MQ9iOUIs2mMU/edit

ni?<the team> for input on direction, content, audience. Does this seem like an appropriate "level" of detail for the audience of "people who might go looking for this on docs.tmo"? Is this missing a ping or a reason or some other sort of information that might be important? Is the organization appropriate for the subject matter?

Planned improvements in translation to docs.tmo include adding links _everywhere_ to reference out to the source docs, and providing styling to headers, lists.

Comment 2

[Alessio Placitelli [:Dexter]]

(In reply to Chris H-C :chutten from comment #1)
> draft:
> https://docs.google.com/document/d/
> 1MWvG2gLCSMFxE8mFQNao_w4mefk9Bg2MQ9iOUIs2mMU/edit
> 
> ni?<the team> for input on direction, content, audience. Does this seem like
> an appropriate "level" of detail for the audience of "people who might go
> looking for this on docs.tmo"? Is this missing a ping or a reason or some
> other sort of information that might be important? Is the organization
> appropriate for the subject matter?

I like the direction this document is taking: it seems to correctly target its audience, being easy to follow and clear. I left a few minor comments on the doc.

Comment 3

[Jan-Erik Rediger [:janerik]]

I like it. Concise and to the point (I would have wished for something like that when I started).

Comment 4

[Georg Fritzsche [:gfritzsche]]

Sorry for the late follow-up.
This is great. I only had some comments, apart from those i'd say let's get this to dtmo!

Comment 5

[Georg Fritzsche [:gfritzsche]]

At some point we should get a data scientist to give a feedback pass.
Either on the gdoc or in the PR. Maybe Su or Jesse?

Comment 6

[Chris H-C :chutten]

Up for review on github: https://github.com/mozilla/firefox-data-docs/pull/196

Tapped Su for a data scientist's perspective.

Comment 7

[Chris H-C :chutten]

Merged!

I'll ni?shong here for Data Science's perspective. I can take any fixups to follow-up patches.

Comment 8

[Su-Young Hong]

Hey guys, this is fantastic. The only suggestion I would make is: 

* To include when (Firefox Version) each of these ping types were implemented. 
* Maybe include a quick paragraph about what pingsender is. 

Look great!

Comment 9

[Chris H-C :chutten]

The follow-up PR[1] has been merged.

[1]: https://github.com/mozilla/firefox-data-docs/pull/198