For what it's worth, I'd suggest updating the descriptions that are already in the schema itself, unless you need to include something that won't fit (like several pages of text or an image).

I haven't had a chance to see how the choice of a readme for content_translation_event has worked out, but I suspect that readmes aren't super discoverable and require the reader to do extra work to cross-reference the readme and the schema itself. So we should probably do our best to avoid having two documents, although of course sometimes we can't (as with content_translation_event or the VisualEditorFeatureUse data dictionary).

Thanks for the suggestion @nshahquinn-wmf! I actually got this idea from the content_translation_event README file you worked on so it's useful to hear your perspective on that.

I created this task because instrumentation changes made as part of T268504 introduced a number of complexities to the ULS schema, which need to be documented. I agree that the descriptions in the schema would be the best central place but not sure it will fit and adequately provide the level of detail that is needed to understand the meaning of each event.action and event.context value.

I'm going to start by identifying all the details I think need to be added to the existing schema documentation and then will coordinate with @jwang (who will be using the data collected in this schema for the Lang Switcher AB Analysis ) to determine the most useful place to document.

Change 713898 had a related patch set uploaded (by MNeisler; author: MNeisler):

[schemas/event/secondary@master] Update ULS Schema descriptions to clarify context field values

https://gerrit.wikimedia.org/r/713898

After reviewing the existing schema documentation, I think the needed clarifications can be added directly to the descriptions within the ULS schema. I've updated the task description and submitted a patch which includes the following updates:

• Add 'languages-list' value to the event.context description. This was added to identify direct clicks to the language links in the sidebar
• Add the 'content-language-switcher' value to the event.context description. This was added to identify clicks to the language links after opening one of the compact language link treatments: the N More button in the sidebar or the new header button
• Update the 'compact-language-links-open' event.action field description to indicate that the context field defines which trigger was used to open the treatment.

There's a lot of additional detail specifically related to deciphering control and treatment sessions in the language switcher AB test. As this context is specific to the AB test, I don't think they need to be included in the schema repo and instead have documented those details in the language switcher instrumentation spec.

Moving this to review for the patch to be reviewed and merged.
(cc @jwang)

Change 713898 merged by jenkins-bot:

[schemas/event/secondary@master] Update ULS Schema descriptions to clarify context field values

https://gerrit.wikimedia.org/r/713898