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
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 couple 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.

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?), they 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'd break the mentor list.

What impact will it have on communities?
Deploying 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. In addition to English Wikipedia beta wiki, structured mentor list is also available at all other beta wikis and the test Wikipedia.

How does it work?
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). To let non-tech savvy community members to be mentors, we created several forms that support all actions that need to be done with a mentor list. In addition to that, the forms also do not require the mentors to be admins to change their information, as it would be normally the case, as the mentor list is in the MediaWiki: namespace.

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. 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).

To ensure the community has control over who is a mentor, administrators will be able to use Special:ManageMentors. 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 use Special:ManageMentors as well, but they do not see the "Remove" button.

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

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