META: Organize glean documentation
Categories
(Data Platform and Tools :: Glean: SDK, enhancement, P3)
Tracking
(Not tracked)
People
(Reporter: mdroettboom, Assigned: mdroettboom)
References
Details
(Whiteboard: [telemetry:mobilesdk:m8])
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.
Assignee | ||
Comment 1•6 years ago
|
||
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.
Updated•6 years ago
|
Updated•6 years ago
|
Updated•6 years ago
|
Comment 2•6 years ago
|
||
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•6 years ago
|
||
(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•6 years ago
|
||
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
Updated•6 years ago
|
Updated•5 years ago
|
Assignee | ||
Comment 5•5 years ago
|
||
Additionally, we also have documentation in probe_scraper
about how to declare a Glean-using app or library for probe scraping.
Assignee | ||
Updated•5 years ago
|
Assignee | ||
Updated•5 years ago
|
Assignee | ||
Comment 6•5 years ago
|
||
The current status:
-
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 -
android-components merely links to (1)
-
probe-scraper includes documentation about adding support for a new Glean-using application or library
-
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)
Updated•5 years ago
|
Description
•