(In reply to Georg Fritzsche [:gfritzsche] from bug 1205835 comment #35) > A request regarding documentation: > Can we land updates to the in-tree documentation along with the actual > changes? > > The Telemetry documentation lives in toolkit/components/telemetry/docs/, the > documentation for this ping could live in core-ping.rst, similar to e.g. > crash-ping.rst. > > I can update that documentation with more details later, but it would be > great to have the in-tree doc on the basic ping contents match that > revisions code. Let's do it in this follow-up.

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

How do I generate these files (to ensure they're properly formatted)?

(In reply to Michael Comella (:mcomella) from comment #2) > How do I generate these files (to ensure they're properly formatted)? From: https://gecko.readthedocs.org/en/latest/ To build the documentation, run mach doc. Run mach help doc to see configurable options.

Comment on attachment 8710793 [details] MozReview Request: Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche https://reviewboard.mozilla.org/r/31869/#review28669 Use `mach doc` to build the documentation, then you can check it locally at `<objdir>/docs/html/Mozilla_Source_Tree_Docs/`. ::: toolkit/components/telemetry/docs/core-ping.rst:2 (Diff revision 1) > +"core" ping We need to add an entry for this file to the `toctree` in `telemetry/docs/index.rst`. ::: toolkit/components/telemetry/docs/core-ping.rst:35 (Diff revision 1) > + "usage": [<pos integer>, <pos integer>], > + // array of total usage time in seconds since last ping and > + // foreground session count, e.g.: [156, 2] > + > + "experiments": [<string>, …], > + // Optional, array of identifiers for the active experiments. > + > + "profileDate": <pos integer>, // Profile creation date in days since > + // UNIX epoch. > + > + "defaultSearch": <string>, // default search engine, e.g. "yahoo" > + "searches": <object>, > + // Optional, object of search use counts in the format: > + // { "engine.source": <pos integer> } > + // e.g.: { "yahoo.searchbar": 3, "other.searchbar": 1 } > + > + "attrib": <string>, // Optional, attribution identifier to correlate > + // to campaigns etc., e.g. "awesome-campaign" Lets limit the documentation to what we actually submit now. We should land updates/additions to the documentation together with future changes, so we match what our products actually send.

https://reviewboard.mozilla.org/r/31869/#review28683 ::: toolkit/components/telemetry/docs/core-ping.rst:29 (Diff revision 1) > + "locale": <string>, // e.g. "en-US" Mention that this is the OS locale.

https://reviewboard.mozilla.org/r/31869/#review28683 > Mention that this is the OS locale. This is actually the application locale (since we override the OS locale with our locale switching behavior early on) – added a comment.

Comment on attachment 8710793 [details] MozReview Request: Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche Review request updated; see interdiff: https://reviewboard.mozilla.org/r/31869/diff/1-2/

Comment on attachment 8710793 [details] MozReview Request: Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche https://reviewboard.mozilla.org/r/31869/#review29325

https://hg.mozilla.org/integration/fx-team/rev/05fa456ff8a782ab9a471a91216a257cf43c0704 Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche

Comment on attachment 8710793 [details] MozReview Request: Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche Optional uplift on top of the uplift for bug 1205835, which will make future uplifts where we also update the docs (e.g. bug 1241697) simpler. Approval Request Comment [Feature/regressing bug #]: bug 1205835 [User impact if declined]: None – uplift is just harder. The docs are pulled from m-c so even the online docs are not changed with this uplift. [Describe test coverage new/current, TreeHerder]: Tested locally. readthedocs.org is also updated. [Risks and why]: None, we're updating in-tree documentation. [String/UUID change made/needed]: None

Comment on attachment 8710793 [details] MozReview Request: Bug 1241599 - Add 'core' ping telemetry docs. r=gfritzsche Simplify your life, taking it. Should be in 45 beta 4