Growth/Structured mentor list

This page describes the team's work on the "Structured mentor list" project. This page contains major assets, designs, open questions, and decisions. Most incremental updates on progress will be posted on the general Growth team updates page, with some large or detailed updates posted here.

Current status

 * 2021-11-22: works begins to plan project
 * 2022-01-15: engineering starts
 * 2022-XX-XX: structured mentor list is available at all beta wikis and at test.wikipedia.org (Phabricator task)
 * Next: Deploy structured mentor list to Growth pilot wikis (Phabricator task)

Summary
The Structured mentor list is a new way for mentors to sign up. Instead of signing up via a wikitext-based list (example), mentors will use forms incorporated into the Mentor dashboard to enroll into mentorship and to change their information, such as their message or number of newcomers they want to be assigned to.

Why are we doing this?
Currently, communities have to maintain a wikitext-based mentor list (example at English Wikipedia, docs), which is a regular wikipage, with no predetermined structure. This approach has a several of disadvantages:


 * Limited extendibility: Mentor's username and their message are separated with a pipe (the  character). This is not an issue when message is the only attribute mentors can configure, but it wouldn't be practical to use the same list to store additional information about the mentor (such as, topics the mentor is interested in or their time availability).
 * Error-prone: When community members make changes to the mentor list, it is very easy to make a mistake and accidentally enroll the wrong user. This happens, because the mentor list is not easy to parse (see the next point).
 * Hard to parse: It is difficult for a machine to "understand" wikitext. This makes it more difficult for both Growth and technical community volunteers to work with the list of mentors and to learn more about how mentorship works at the various wikis. Switching to the structured mentor list will make it easier.
 * Hard to set up: Each community that wants to adopt Growth mentorship has to create its own mentor list. While there is documentation on how to do it, it often requires the help of the Growth team. With the structured mentor list, the only step needed to get Growth mentorship will be to get a sufficient number of mentors on board.

The Structured mentor list resolves all of those issues. Because the data is stored in a JSON page in the MediaWiki: namespace (see #How does it work?), the list can be easily extended or parsed by a machine. Since mentors change information in the list via a form (rather than editing the list directly), it is harder to make a mistake that would break the mentor list.

What impact will it have on communities?
Deploying the Structured mentor list to a wiki will change most mentorship-associated workflows. For instance, instead of going to a wikitext-based mentor list to enroll, a soon-to-be mentor will have to go to their Mentor dashboard to enroll, or to change information about themselves. The Growth team will take care about converting the wikitext mentor list to the new structured mentor list, so no information will be lost.

It might be necessary to update the wikitext mentor list to include useful information (such as, where to enroll or what mentorship is). It is also possible to delete it, and rely on the Mentor dashboard to provide all necessary information to the mentors.

In case you want to test the project in advance, you can! Testing instructions can be found at Wikimedia Phabricator. The Structured mentor list is available at all beta wikis and the test Wikipedia.

Configuration
Conceptually, the Structured mentor list is similar to the Community configuration project, where the Growth team decided to keep certain settings in an on-wiki JSON page. Similar to what Community configuration does, the actual list of mentors is stored in a JSON page in the MediaWiki namespace, called MediaWiki:GrowthMentors.json (see an example at test.wikipedia.org). We created several forms that support all actions that need to be done with a mentor list that should be easy to utilize. In addition to that, the forms do not require that mentors have admin permissions in order to change their information, as the mentor list is in the  namespace.

Mentors' signup and customization
Non-mentors who want to sign up as mentors can use the Mentor dashboard to sign up. To ensure only trusted users can enroll as a mentor, two new mentorship-related options are available within Community configuration (see image on the right). Using those options, community will be able to define minimum requirements for mentors: a minimum number days of presence and a minimum number of edits. Mentor dashboard will ensure that only mentors who meet the minimum criteria are allowed to sign up.

Mentors who want to edit their introduction message, change how many mentees they are assigned, or take another action related to mentorship, will be able to do so via the Mentor dashboard as well. Each mentor will be only able to change their own details (for instance, mentor Jane is only able to change her own message; she will be unable to change John 's message).

Community control of Mentors
To ensure the community has control over who is a mentor, administrators will be able to use. This special page shows a list of mentors, and allows admins to remove any of them. If the "Remove" button is clicked, they're removed from the mentor list, and all their mentors are assigned to a different mentor. Non-admins can visit  as well, but they do not see the "Remove" button.

All changes made by mentors, enrolling users, or administrators will show in the MediaWiki:GrowthMentors.json page history.

In case direct access to the mentor list is needed, administrators and interface administrators are able to edit the underlying JSON page directly.