1529761 - META: Organize glean documentation

Status: RESOLVED FIXED

(Data Platform and Tools :: Glean: SDK, enhancement, P3)

Description

[Michael Droettboom [:mdroettboom]]

We currently have:

(1) General documentation about how glean works in android-components

(2) Documentation about metric types and the various parameters in a Google Doc

(3) API documentation for the Kotlin implementation

(4) API documentation for glean_parser

I would propose that we merge (1) and (2) in a central location, and start using version control to manage it. (3) and (4) would continue to exist in their language-specific form next to the source code, but would simply link to (1/2) for further general information about glean.

Comment 1

[Michael Droettboom [:mdroettboom]]

It was also noted that there is a major reorganization of the code pending as part of the oxidation effort. I think even when that happens, this documentation organization makes sense, even if all the parts live in the same repo, for example.

Comment 2

[Georg Fritzsche [:gfritzsche]]

Could we, for now, keep (1) and (2) in android-components and move it to the single, separate Glean repository once that is active?

That would keep documentation changes side-by-side with the code changes.
Keeping things up-to-date in two separate locations seems harder to track.

I think for Desktop Telemetry, we had good experiences with the library documentation living side-by-side with the code.

Comment 3

[Alessio Placitelli [:Dexter]]

(In reply to Georg Fritzsche [:gfritzsche] from comment #2)

Could we, for now, keep (1) and (2) in android-components and move it to the single, separate Glean repository once that is active?

+1 on this.

Comment 4

[Chenxia Liu [:liuche]]

As a follow-up to https://github.com/mozilla-mobile/android-components/pull/2353, two comments:

• Update samples to include an expiry, not never: https://github.com/mozilla-mobile/android-components/pull/2353#discussion_r265665187
• Add context around usage of expires: never, and explain it should only be applied to Glean SDK baseline metrics, or require prior approval: https://github.com/mozilla-mobile/android-components/pull/2353#issuecomment-472959449

Comment 5

[Michael Droettboom [:mdroettboom]]

Additionally, we also have documentation in probe_scraper about how to declare a Glean-using app or library for probe scraping.

Comment 6

[Michael Droettboom [:mdroettboom]]

The current status:

1. The main Glean documentation lives in github.com/mozilla/glean and includes:

   a) User documentation
   b) Developer documentation
   c) Kotlin API docstrings
   d) Rust core (non-public API) docstrings

2. android-components merely links to (1)

3. probe-scraper includes documentation about adding support for a new Glean-using application or library

4. glean_parser includes:

   a) some documentation about the metrics.yaml format.
   b) Python API docstrings for users of glean_parser (which includes probe_scraper as well as the Glean build itself)