Assuming that any instruments using the base schemas and the monotable streams must provide an instrument name, I suggest that all examples in the docs use Instrument. That way we can avoid the complexity of presenting different methods of using the API, especially since the DRYness of using Instrument is a better developer experience. What do you think?

Neato! This also allows us to remove the section that I added, DRYing up the docs themselves.

Assuming that any instruments using the base schemas and the monotable streams must provide an instrument name, I suggest that all examples in the docs use Instrument. That way we can avoid the complexity of presenting different methods of using the API, especially since the DRYness of using Instrument is a better developer experience. What do you think?

I've taken a swing at this in https://wikitech.wikimedia.org/w/index.php?title=Metrics_Platform%2FJavaScript_API&diff=2237753&oldid=2236880. However, I'm not quite sure where to introduce the Instrument class. At the beginning? In the Implementation section? What do you think @apaskulin.

Looking at the code, it seems that the submitClick and submitInteraction methods will accept any InteractionData fields as long as they validate against the specified schema. I've opted to document this functionality as-is in the docs instead of recommending a specific set of interaction data fields. This way we can use other sources (like the instrumentation spec instructions) to provide guidance about which interaction data fields to use. Let me know if you'd prefer to be more prescriptive in these docs, and I can add back the list of recommended fields.

👍

Is there any way to test the code samples in the docs automatically?

I thought about this for a while but I can't see a way to do this on-wiki, scoped to the Metrics Platform documentation.

We could convert the page to a literate JavaScript program in the Metrics Platform repo and then export it to https://wikitech.wikimedia.org/wiki/Metrics_Platform/JavaScript_API when it's updated 🤔

Thanks, @phuedx! Your edits looks great.

In T377619#10249378, @phuedx wrote:

I've taken a swing at this in https://wikitech.wikimedia.org/w/index.php?title=Metrics_Platform%2FJavaScript_API&diff=2237753&oldid=2236880. However, I'm not quite sure where to introduce the Instrument class. At the beginning? In the Implementation section? What do you think @apaskulin.

I've added a "Create an instrument" section, and broken out the code sample there. I'm curious: What happens if I specify a custom schema in newInstrument then use submitClick?

We could convert the page to a literate JavaScript program in the Metrics Platform repo and then export it to https://wikitech.wikimedia.org/wiki/Metrics_Platform/JavaScript_API when it's updated 🤔

This sounds awesome, but it seems like more of an optimization at this stage in the project. Maybe we leave the code samples as-is for now and revisit later if we run into issues with the samples falling out of date?

In T377619#10251787, @apaskulin wrote:

<snip /> I'm curious: What happens if I specify a custom schema in newInstrument then use submitClick?

It turns out that mw.eventLog.submitClick() and Instrument#submitClick() both use the latest version of the Web Base schema. Maybe this is a bug? Regardless, this is counterintuitive in the case of Instrument#submitClick(). I'll create a task to update this behaviour. When I've done that, should I add a note to the docs?

We could convert the page to a literate JavaScript program in the Metrics Platform repo and then export it to https://wikitech.wikimedia.org/wiki/Metrics_Platform/JavaScript_API when it's updated 🤔

This sounds awesome, but it seems like more of an optimization at this stage in the project. Maybe we leave the code samples as-is for now and revisit later if we run into issues with the samples falling out of date?

Agreed.