User:Jmatazzoni/drafts

Event Metrics (formerly known as Grant Metrics) enables organizers of events like editathons and content drives to get metrics about those events in order to understand and demonstrate the scale and impact of their contributions. Wikimedia grantees can use the program to provide grant documentation (such as metrics listed at Grants:Metrics). Event Metrics works with the following projects: Wikipedias, Wikivoyages, Wiktionaries, Commons and Wikidata.

To begin using Event Metrics, organizers first create a Program, which is an overall category for a series of events. Individual Events live inside Programs. For example, a Program might be be “Smallville Library Events, 2019." Events inside this program could be "Town History Month" or "Earth Day, 2019," etc. Users can compute metrics for each event and also look at metrics overall for a given program. Below is a detailed walkthrough for how to use the app.

Metric definitions

Learn what metrics are provided by the various Event Metrics reports and about the properties and limitations of each data type.

• Definitions of metrics

Landing page

Getting started

Landing page

When you go to Event Metrics for the first time, you are presented with a landing screen that looks like this. It prompts you to login with OAuth. The background image is pulled from Commons, so every time you refresh, you see a new one!

OAuth dialog box

Logging in

When you click on "Login with OAuth", you're presented with a dialog box which asks for your permission to provide Event Metrics with your username. The app doesn't pull any other data from your account.

My programs (Home page)

My programs page

When you login with OAuth, you land on "My Programs" page. This page lists all of the programs that you're an organizer for. Anyone can create a program and anybody can be added as a program organizer. Keep in mind that only program organizers can create and edit events for a given program.

Note the two icons in front of every program? The gear icon is for modifying a program and the red delete icon is for deleting a program.

Keep in mind though that programs with events inside them cannot be deleted. You can create a new program by clicking the 'Create a new program' button on the right.

Creating a new program

The metrics you see next to the program and combined metrics for all of the events in a program. We'll touch upon how to generate them below.

Creating a new program

By clicking the 'Create a new program' button in the previous screenshot, you come to this screen. Here you can create a new program by adding a program title and adding organizers for the program. Note that the creator of the program is automatically added as an organizer and cannot remove themselves. Note that the app will not let you save the participants list if a user you added as organizer is not registered.

New program

New program on homepage

Once you add your program, you can come back to the home page (by clicking "My programs" link on top). Your new program will be there! But it doesn't have any events yet, so let's create one. You can go inside the program by clicking the program title. In this case "Women in Red".

Inside a program

Program page

This is the program view page. It lists the organizers on the left. You can click on them to see their Meta user page. It's empty right now because we don't have any events for it. We can create an event by clicking the "Create a new event" button.

Creating a new event

Creating an event

When you click the "Create a new event" button in the previous screen, you land on the Event Setting page. In order to create a new event, you need to fill in the form pictures at left with:

• A unique title for the event

• Wikis on which the event will run: Enter the wikis where you want to track metrics. Start typing the language code for any wiki, and a menu will offer to autocomplete. Contributions will be tracked on the specified wikis only. But impact metrics will not be limited to these wikis. E.g., if you specify Commons, you’ll get metrics about the files you upload to Commons. But you’ll get pageview metrics for those files from every wiki where those files get placed.

• Per-wiki limit of 50,000 pages tracked: For each wiki in your event, Event Metrics will track a maximum of 50,000 pages (on Wikipedias and similar projects). On Commons, it will track up to 50,000 files, and on Wikidata that same number of items. If you expect your event to be bigger than that, try breaking it up. E.g, instead of trying to track all the categories or users in one event, spread them over multiple events.

• Date and time for the event duration (along with your preferred timezone).

When you Save your settings, the system creates the event and delivers you into the main Event Summary page. But your job is not yet complete: you must also provide filtering.

Filtering

The Event Summary page when no filters have been applied yet. A red error message explains the filtering requirements.

Filtering is required

You can save an event without filters, but you won’t get metrics for the event until you add either Participants or Categories filtering—you can also combine both types. Here's a summary of the basic filtering requirements and of how the two filter types interact. The system will remind you of these rules during setup (see illustration).

• You must provide filtering for every wiki for which you want metrics.

• Participants filtering applies to all wikis and satisfies all minimum filtering requirements by itself.

• Category filters are specific to individual wikis because each wiki has different categories.

• If you use Categories without Participants, you must provide a category for every wiki for which you want metrics. If you provide categories for some wikis only, you’ll get metrics only for those wikis.

• If you combine Categories and Participants, contributions tracked will be those that satisfy both filters (i.e., Category AND Participants).

The two filtering type have different properties and restrictions, which are explained in the next sections.

Adding Participants. The red icon indicates an invalid username. The system won't Save any of the names until you correct or remove the invalid one.

Filter by Participants

To filter an event by Participants, you enter and save a list of wiki usernames. Once you do, reports for that event will track contributions only from those users.

• Covers all minimum filtering requirements: If you use a Participants list, you will get results for all wikis you specified in Event Settings and for all contribution types. If Wikidata is part of your event, you must supply Participants (Wikidata doesn't use Categories, so Category filtering is not available there).

To add Participants

• Type or paste wiki usernames, one per line, in the large text box (see illustration). Save the list. Usernames can include both underscores and spaces.

• Username validation: The list will update, as pictured. The green ticks indicate valid—meaning registered—usernames. The red symbol indicates that the username does not exist.

• You must remove or fix invalid usernames and click 'Save Participants' in order for your changes to be saved. Invalid names will prevent you from Saving any of the names. If you're having trouble saving a username, check for incorrect spelling, capitalization and extra formatting like bullets, spaces, commas etc.

• Automatic formatting of wiki lists: You can copy paste participants directly from on-wiki lists and they should be formatted correctly. For example, you can select all the participants you see on this page and paste them in the input box on Event Metrics and they appear formatted correctly, one per line.

Adding Categories. You must enter a wiki name for each category.

Filter by Categories

Category filtering restricts metrics to pages and files that are in the a specified category or group of categories.

• Categories are wiki specific: You must name a wiki for each category you provide. The category will apply only to that wiki.

• Main namespace only: For filtering purposes, categories must by must be applied to main/article namespace pages. E.g., talk page categories won’t work. Commons is an exception (see below).

• Applies to files on Commons: On Commons only, Category filtering works for uploaded files, including images, videos, audio files, etc.

• Subcategories are not tracked automatically. If you want to include subcategories, you must specify them directly.

• Hidden categories are allowed by the system. (Make sure to check with the policies and practices governing the use of hidden categories on your local wiki).

Categories without Participants

• Categories are wiki-specific: If you use Categories filtering without Participant filtering, you must supply a category for every wiki about which you want metrics. If you don’t, you'll get metrics only for the wikis that are filtered. (As described above, Participants filtering automatically covers every wiki and contribution type.)
• No Wikidata metrics: Categories don’t exist on Wikidata (in the normal sense), so if you don’t supply  a Participants list, you will see no metrics about Wikidata items
• No local file uploads: Category filtering applies only to pages on all wikis except Commons; it won’t work for files uploaded directly to Wikipedias. So if you want to track uploads directly to Wikipedias, you must include a  Participants list.

Adding categories. The red icon indicates an invalid entry. When saving a group of categories, you must remove or fix all invalid entries before any valid entries can be saved.

To add categories

• First enter the wiki name by typing the abbreviation for the name of a  wiki (see list of wikis with language abbreviations). A menu should appear to offer to autocomplete. Next enter the category name; again, a menu should appear to autocomplete (it's always safer to select from the menu if you can). Add one category per line; click the + Add category link to add as many lines as you need. When you are finished, Save the list.
• Category validation: The list will update, as pictured. The red symbol indicates an invalid name.
• You must remove or fix invalid categories and click Save in order for any of your changes to be saved. Invalid categories will prevent valid ones from being saved as well. If you're having trouble saving a category, check for incorrect spelling, capitalization and extra formatting like bullets, spaces, commas etc. Always use autocomplete when possible, to ensure accuracy.

Getting reports

Event Metrics provides four downloadable reports (links are to a list of the metrics in each report):

• Event Summary offers an overview of event contributions, impact and participation.
• Pages Created lists all the new pages saved during your event and provides details about each one, including the size of its cumulative and daily audience.
• Pages Improved is similar to Pages Created but more comprehensive, listing all the articles edited during the event.
• All Edits is a chronological list of every action saved by event participants.

To download a report

• You must ‘Update data’ Make sure your metrics are up to date by selecting the ‘Update data’ button. Updating is always manual; the system will not recalculate metrics unless you tell it to. Every downloded report includes a “Last updated” notation that tells you how fresh the figures are, and the current update date is displayed next to the ‘Update data’ button.
• Use the ‘Download reports’ menu to select the desired report.
• Select wikitext or spreadsheet (csv): One you select a report, a popup selector will ask you to choose one of two formats: Wikitext, which you can paste directly into a wiki page in order to share metrics publicly; or Spreadsheet files (csv), which let you sort metrics and publish them in reports.

To view 'All Edits'

Clicking the "View all edits" link next to the Contributions label on the Event Summary page takes you to the All Edits page. There you'll see a reverse-chronological list of every edit made by participants on your list, on the wikis your event ran on, over the duration of the event.

You can download all All Edits data a CSV file or export it as a wikitable using the Download Reports menu, as above.

Troubleshooting

Something doesn't work as expected? You could try...

• Using a different browser

• Restricting the participant list or the number of wikis or the duration of your event

If you find a bug, congratulations! You found one despite our extensive testing! Please take the time to file a bug report on Phabricator. Or tell us about it on the discussion page. We'll try to get back to you as soon as possible.