Make about:telemetry start page a useful entry point into Telemetry

RESOLVED FIXED in Firefox 57

Status

()

enhancement
P1
normal
RESOLVED FIXED
2 years ago
2 years ago

People

(Reporter: gfritzsche, Assigned: flyingrub)

Tracking

(Blocks 1 bug)

Trunk
mozilla57
Points:
---
Dependency tree / graph

Firefox Tracking Flags

(firefox57 fixed)

Details

Attachments

(1 attachment)

We now have a home/start page for about:telemetry, which we could use as a good entry point to our docs or other services.

We could add visible pointers to:
- client telemetry docs
- fx data docs
- t.m.o services
- others?

One concern here is that about:telemetry ships on the trains, so we should use relatively stable URIs.
Ryan, Mark, what do you think about this?
Flags: needinfo?(rharter)
Flags: needinfo?(mreid)
I don't have a strong opinion. Folks should be able to get to the docs using search pretty easily. Seems like a nice-to-have.
Flags: needinfo?(rharter)
Do we have any documentation about "about:telemetry" itself? If we had that kind of info (at a stable URI, which is a good point!), that would be my vote.
Flags: needinfo?(mreid)
We don't have any documentation on using about:telemetry.
Maybe we could just add whatever explanations we need to the about:telemetry page itself?
Priority: -- → P4
Blocks: 1384534
Assignee: nobody → flyinggrub
Status: NEW → ASSIGNED
Priority: P4 → P1
I'm suggesting:

> Looking for more information?
> - The [Firefox data documentation](...) contains guides and references on how to work with our data tools.
> - The [Firefox Telemetry client documentation](...) includes definitions for concepts, API documentation and data references.
> - The [Telemetry dashboard](...) contains starting points to accessing the Telemetry data.

To not block on immediate improvements now i think we can re-visit the "stable URI" problem in the future.
Worst-case is that the links break in older versions, until then we at least added value.

The URLs for these are:
1) https://docs.telemetry.mozilla.org/
2) https://gecko.readthedocs.io/en/latest/toolkit/components/telemetry/telemetry/index.html
3) https://telemetry.mozilla.org/

The only address we don't control is 1). We could see if we could use a mzl.la alias or similar so we could redirect it in the future.
That would also address the current issue we have with the "ping" explanation link.
flod, does anything here look problematic from a l10n/strings perspective?

For the record, this is the current only link to docs:
https://dxr.mozilla.org/mozilla-central/rev/a6a1f5c1d971dbee67ba6eec7ead7902351ddca2/toolkit/locales/en-US/chrome/global/aboutTelemetry.properties#56
Flags: needinfo?(francesco.lodolo)
(Clearing NI per IRC discussion, not the right person for this question)
Flags: needinfo?(francesco.lodolo)
Dao, do you happen to know if we have any prior art or best practices on something like comment 2?
Flags: needinfo?(dao+bmo)
(In reply to Georg Fritzsche [:gfritzsche] from comment #8)
> Dao, do you happen to know if we have any prior art or best practices on
> something like comment 2?

I mean comment 5.
Comment on attachment 8899425 [details]
Bug 1381831 - Improve about:telemetry start page

https://reviewboard.mozilla.org/r/170702/#review175828

::: toolkit/locales/en-US/chrome/global/aboutTelemetry.dtd:16
(Diff revision 1)
> +<!ENTITY aboutTelemetry.telemetryState "
> +Telemetry State
> +">
> +
> +<!ENTITY aboutTelemetry.moreInformations "
> +Looking for more information ?

Why the space before a question mark?

::: toolkit/locales/en-US/chrome/global/aboutTelemetry.dtd:27
(Diff revision 1)
> +
> +<!ENTITY aboutTelemetry.telemetryClientDoc "
> +The <a>Firefox Telemetry client documentation</a> includes definitions for concepts, API documentation and data references.
> +">
> +<!ENTITY aboutTelemetry.telemetryDashboard "
> +The <a>Telemetry dashboard</a> contains starting points to accessing the Telemetry data.

"to accessing" should be "to access"?
Comment on attachment 8899425 [details]
Bug 1381831 - Improve about:telemetry start page

https://reviewboard.mozilla.org/r/170702/#review175848

::: toolkit/content/aboutTelemetry.js:1824
(Diff revision 1)
>    let subtitleElement = document.getElementById("page-subtitle");
>    subtitleElement.appendChild(document.createTextNode(subtitleText));
> +
> +  let links = [
> +    "https://docs.telemetry.mozilla.org/",
> +    "https://gecko.readthedocs.io/en/latest/toolkit/components/telemetry/telemetry/index.html",

Does it work without the 'en/'? I know mozilla sites auto-detect locale if you remove it, which could make it better for non-English users.

::: toolkit/content/aboutTelemetry.xhtml:151
(Diff revision 1)
> +          <li>&aboutTelemetry.firefoxDataDoc;</li>
> +          <li>&aboutTelemetry.telemetryClientDoc;</li>
> +          <li>&aboutTelemetry.telemetryDashboard;</li>
> +        </ul>
> +        <br></br>
> +        <h4>&aboutTelemetry.telemetryState;</h4>

I think you should omit the Telemetry State header and put the More Information section below the state. Then it would be:

Home
This page shows the information....
Telemetry is enabled....
Each piece of information is sent...

Looking for more information?
* item 1
* item 2...

::: toolkit/locales/en-US/chrome/global/aboutTelemetry.dtd:20
(Diff revision 1)
> +<!ENTITY aboutTelemetry.moreInformations "
> +Looking for more information ?
> +">
> +
> +<!ENTITY aboutTelemetry.firefoxDataDoc "
> +The <a>Firefox data documentation</a> contains guides and references on how to work with our data tools.

Skip "and references"

Replace "on" with "about"

docs.tmo's title is "Firefox Data Documentation" in title case. You should capitalise the 'd's in the link.

::: toolkit/locales/en-US/chrome/global/aboutTelemetry.dtd:27
(Diff revision 1)
> +
> +<!ENTITY aboutTelemetry.telemetryClientDoc "
> +The <a>Firefox Telemetry client documentation</a> includes definitions for concepts, API documentation and data references.
> +">
> +<!ENTITY aboutTelemetry.telemetryDashboard "
> +The <a>Telemetry dashboard</a> contains starting points to accessing the Telemetry data.

It's "Telemetry dashboards" and perhaps we can rewrite as:

The <a>Telemetry dashboards</a> allow you to visualize the data Mozilla receives via Telemetry.
Attachment #8899425 - Flags: review?(chutten) → review-
Comment on attachment 8899425 [details]
Bug 1381831 - Improve about:telemetry start page

https://reviewboard.mozilla.org/r/170702/#review175848

> Does it work without the 'en/'? I know mozilla sites auto-detect locale if you remove it, which could make it better for non-English users.

It doesn't seems to work here : https://gecko.readthedocs.io/latest/toolkit/components/telemetry/telemetry/index.html
Comment on attachment 8899425 [details]
Bug 1381831 - Improve about:telemetry start page

https://reviewboard.mozilla.org/r/170702/#review175904

::: toolkit/locales/en-US/chrome/global/aboutTelemetry.dtd:12
(Diff revision 4)
>  <!ENTITY aboutTelemetry.pingDataSource "
>  Ping data source:
>  ">
>  
> +<!ENTITY aboutTelemetry.telemetryState "
> +Telemetry State

You shouldn't check in unused strings.
Attachment #8899425 - Flags: review?(chutten) → review-
Comment on attachment 8899425 [details]
Bug 1381831 - Improve about:telemetry start page

https://reviewboard.mozilla.org/r/170702/#review176254

r+ pending l10n's input on final strings.
Attachment #8899425 - Flags: review?(chutten) → review+
(In reply to Chris H-C :chutten from comment #19)
> Comment on attachment 8899425 [details]
> Bug 1381831 - Improve about:telemetry start page
> 
> https://reviewboard.mozilla.org/r/170702/#review176254
> 
> r+ pending l10n's input on final strings.

No issue on my side for strings.
(In reply to Georg Fritzsche [:gfritzsche] from comment #5)
> To not block on immediate improvements now i think we can re-visit the
> "stable URI" problem in the future.
> Worst-case is that the links break in older versions, until then we at least
> added value.
> 
> The URLs for these are:
> 1) https://docs.telemetry.mozilla.org/
> 2)
> https://gecko.readthedocs.io/en/latest/toolkit/components/telemetry/
> telemetry/index.html
> 3) https://telemetry.mozilla.org/
> 
> The only address we don't control is 1). We could see if we could use a
> mzl.la alias or similar so we could redirect it in the future.
> That would also address the current issue we have with the "ping"
> explanation link.

I think you meant 2)? We should use some mozilla-controlled address and redirect. According to a recent firefox-dev e-mail we're in fact moving away from Read The Docs.
Flags: needinfo?(dao+bmo)
Well that was quick. We now control where the Mozilla Source Tree Documentation lives: https://firefox-source-docs.mozilla.org
The new location is something we control.
Unless there are other concerns, let's move ahead.
Keywords: checkin-needed
Keywords: checkin-needed
Rebased on m-c and updated the link :)
Keywords: checkin-needed
Pushed by ryanvm@gmail.com:
https://hg.mozilla.org/integration/autoland/rev/5ffb2108ba51
Improve about:telemetry start page r=chutten
Keywords: checkin-needed
https://hg.mozilla.org/mozilla-central/rev/5ffb2108ba51
Status: ASSIGNED → RESOLVED
Closed: 2 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla57
You need to log in before you can comment on or make changes to this bug.