1703280 - Merge metrics parameter documentation in glean_parser documentation into the Glean book

Status: RESOLVED FIXED

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

Description

[Michael Droettboom [:mdroettboom]]

There are currently two sources of information about parameters in metrics.yaml files:

• In the glean_parser documentation here, which is semi-auto-generated from the schema itself
• In the Glean book here

Both of these are incomplete in different ways, and users may land on one or the other depending on where they are coming from.

There should be a single published location for this information in the Glean Book, and the glean_parser documentation should be reduced to developer-only docs (with links to the Glean Book for backward compatibility). It should include all currently-accepted parameters, though the metric-type-specific parameters should remain documented on the metric-specific documentation pages as they are today. (This was partially done in bug 1562681, but the copy in glean_parser wasn't removed, and the Glean Book may have become out-of-date).

Ideally, the source of truth for this should be the schema itself. This does pose a set of unique challenges -- (a) pulling in content from another repository and (b) generating markdown from JSON schema using mdbook tooling. All of that may be more effort than its worth and perhaps just manually maintaining the markdown docs for metric parameters in the Glean Book source would be sufficient.

Comment 1

[Michael Droettboom [:mdroettboom]]

:chutten -- ?ni just in case you have additional thoughts as the most recent person to stumble on this.

Comment 2

[Chris H-C :chutten]

I searched for yaml in the Glean User Book, and it didn't come up with much. Definitely didn't come up with the list of optional parameters. So then I looked for docs in the glean_parser doc that showed up in my awesomebar history and had to scroll to the published schema to find it.

And, hm, now that I know what it's called, searching on the Glean Book for sensit finds a couple of results but sensiti doesn't. And on up to sensitivit. sensitivity finds the same results.

That seems like a different bug.

---

All in all I'm in favour of one definitive location plus links to it from other places. I don't know how many folks even know that glean_parser has docs, so the Glean Book seems like the correct place to me.

Comment 3

[GitHub Bugzilla PR Linker]

Attachment: Link to GitHub pull-request: https://github.com/mozilla/glean/pull/1574

Comment 4

[GitHub Bugzilla PR Linker]

Attachment: Link to GitHub pull-request: https://github.com/mozilla/glean_parser/pull/303