Status udate:

1st AC is already covered by recent documentation updates - see https://wikitech.wikimedia.org/wiki/Metrics_Platform/Implementations#API

2nd AC can be verified by reviewing https://wikitech.wikimedia.org/wiki/Metrics_Platform/Creating_a_Custom_Schema

3rd AC can be verified by reviewing https://wikitech.wikimedia.org/wiki/Metrics_Platform/Validating_Events (though still missing PHP instructions)

Additional deployment documentation:
https://wikitech.wikimedia.org/wiki/Metrics_Platform/How_To/Deploy_a_New_Version

There are still a few sections that need adding, namely:

• PHP end-to-end testing section
• PHP deployment instructions
• a section/page on dashboards for production streams

Moving this to review for the time being while T351294 is being actively worked on.

After reviewing a long while all these documentation (and other documents related during last weeks) I wanted to say that I was able to run a mediawiki container, configure Metrics Platform and test all the functions that currently work with Metrics Platform (submitInteraction, submitClick, dispatch and submit). I also learned how to test WikimediaEvents and it seems to be an important extension to run instruments right now. I think existing documentation is good but the process was a little hard and, I think, the reason is that the knowledge is too much spread out through a lot of different pages/documents. And outdated and new documents coexist and that creates extra confusion because you don't know which is the right path. I have been trying the right function with the wrong schema/configuration and vice versa several times. As I said, I think all those pages are really good but, in addition to that, we'd need more pages like https://wikitech.wikimedia.org/wiki/Event_Platform/Instrumentation_How_To (I think this one is a bit outdated because it doesn't use Metrics Platform but the structure is interesting because it shows the full lifecycle of an event).

I think it would be really useful to add a “Getting started with” document/s where you can find practical examples for all the different scenarios you can need (all the different ways to create events). Maybe even for the deprecated functions because I guess it’s something we will find somewhere in the code right now and for a long time while migrating all this to the new and definitive functions. Because the knowledge is too much spread out in different pages, it’s difficult to put the right pieces together to see and run a full sample flow (creating a new or reusing a previous schema, sample function/code to use with the instrument code, stream configuration and what the event looks like).

If the purpose is to deprecate some of these functions (I think it’s), maybe we should do that in two separate documents/pages/sections: one dedicated to instrument creators and others only for maintainers (for the Metrics Platform team or other teams who have to maintain their existing instruments). We could split the functions in both groups of documents depending on who are the target users.

For my own understanding of all this I am creating my own “Getting started with Metrics Platform “ document (https://docs.google.com/document/d/1cxhQqkSYECdgffdUxYIaAudbzxxLPPXFDdM0qnGv4rQ/edit) with a summary of all the different ways of running Metrics Platform right now. That way I can see every function definition, its configuration and how I can run it with some practical examples. My purpose is not to create any initial structure at all. It’s just a small sample of what I think we could need: just easy practical examples with code to be able to run them by ourselves to see, quickly, how things work before continuing reading, at least for a simple situation for every scenario or flow.

In addition to that, I also missed a clear documentation about what I need to run/configure properly Metrics Platform with my mediawiki container. There is a page (https://www.mediawiki.org/wiki/MediaWiki-Docker/Configuration_recipes/EventLogging) with some recipes but it's not always clear which one you have to use to configure Metrics Platform properly in your instance. Or what you need to run MediaWikiEvents (I think you don't need the same configuration for both).

https://wikitech.wikimedia.org/wiki/Metrics_Platform/Validating_Events#Javascript is another good sample of what I try to explain. You can find a complete sample about how to configure a new stream and how to produce an event through it. It's something you can try and run to see how Metrics Platform runs. But it's just about one of the four different functions.

• By the way, according to this page, "Validating_Event", we should run mediawiki and a local EventGate instance according to https://www.mediawiki.org/wiki/MediaWiki-Docker/Configuration_recipes/EventLogging#Event_Platform_with_Local_Schema_Repositories but I'd say the right place is https://www.mediawiki.org/wiki/MediaWiki-Docker/Configuration_recipes/EventLogging#Event_Platform and https://www.mediawiki.org/wiki/MediaWiki-Docker/Configuration_recipes/EventLogging#Event_Platform but I'm not sure. I read that here (https://wikitech.wikimedia.org/wiki/Metrics_Platform/Creating_An_Instrument#In_MediaWiki_Docker) where documentation says: "Even if you have previously installed this Event Platform environment, make sure you have completed the instructions of the Metrics Platform section on that page. The Legacy EventLogging and Event Platform with Local Schema Repositories sections are not needed". This is one of the misunderstanding I have mentioned before about how to configure properly mediawiki to be able to work with Metrics Platform

Does all this make some sense? I don't have provided too many specific samples about all I have mentioned because sometimes I'm not sure if I'm right or wrong or I'm understanding well. I just provided my point of view and some samples about what I think are inconsistencies. Anyway, if appropriate, I could create a document to collect all the inconsistencies found in the documentation according to all this, to try to fix one by one and organize it.