This task is part of a project to establish a formal review process and set of standards for Wikimedia technical documentation. For more information, visit the project page on mediawiki.org
Page
https://www.mediawiki.org/wiki/Developers/Maintainers
Content review
What is the topic of the page?
- Code ownership and stewardship, with the (perhaps misleading) implication that the content should be useful to guide the reader to someone who is knowledgeable about or able to provide support related to a specific extension, library, etc.
Does the page fit into to a defined content type?
- This is a reference doc.
What information is included on the page?
- Lists of developers and code maintainers for:
- MediaWiki core
- MediaWiki extensions deployed at Wikimedia Foundation
- MediaWiki skins deployed at Wikimedia Foundation
- Libraries deployed with MediaWiki at Wikimedia Foundation
- MediaWiki core libraries
- MediaWiki extension libraries deployed at Wikimedia
- Upstream projects and libraries
- Operations/systems administration
- Data Engineering
- MediaWiki core
Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?
- Unclear. See notes below in "Recommendations".
Are there any duplicate pages or overlapping content that needs to be merged or marked as obsolete?
- N/a
How is the page linked to related pages? What categories does the page belong to? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.
- This page is in "Category:MediaWiki_development".
- The closest related collection is probably the Development Guidelines collection and its various instructions about how to get review and interact with other technical contributors.
Content checklist
- Title style: Uses sentence case for titles. The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is much better than "Instances".
- I wish I could change the title of this page to be more descriptive and not use a \, but I think that would break too many links. So, leaving as-is.
- Introduction: Added an intro sentence and cleaned up the first sections to have better structure.
- Table of contents: Moved to be right-aligned.
- Section headings
- Code samples: n/a
- Links: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
- Multiple rows in the table link to https://www.mediawiki.org/wiki/Core_Platform_Team which redirects to a page that is marked as a draft.
- Link text for "Product Infrastructure" links to https://www.mediawiki.org/wiki/Wikimedia_Product/Component_responsibility#Extensions
- https://www.mediawiki.org/wiki/Wikimedia_Product/Component_responsibility has a banner: "This page may not reflect reality. Please see Developers/Maintainers"
Addressing the utility and formatting of links in this page should be done in conjunction with updating the actual list of developers, maintainers, technologies, teams etc. That is out of scope for this task. I did remove or fix the following dead links:
- https://www.mediawiki.org/w/index.php?title=Manual:Metrics&action=edit&redlink=1
- https://www.mediawiki.org/w/index.php?title=Extension:Wikidata.org&action=edit&redlink=1
- https://www.mediawiki.org/w/index.php?title=Core_Platform_Team/Initiatives/API_Gateway/Documentation_Plan&action=edit&redlink=1
- Lists: Do not use bulleted list items to complete an introductory sentence fragment.
- Status: It might be more honest if this page had a "this info may be out of date" banner, but I don't feel empowered to make that decision, and the current banners seem fine.
- Feedback and communication: There's a link to a phab task that is tracking the needed updates to this page's content.
- Translation: If translation is available and the content of the page is stable, the page is marked for translation.
- N/A
- Mobile : This page is not even really readable on desktop: the tables are too wide. Long-term, it would be better to put this information somewhere that it can be automatically maintained or more easily searched (i.e. a spreadsheet or something more appropriate for tabular data than a wiki page). I'm not going to try to fix this in this bug.
- Accessibility: The biggest issues were low contrast in table cells that had red backgrounds but included linked text. I removed the red background because skimming this content to find red blobs is probably not the most accurate way to interact with the content, and there were already some cells that had "unassigned" but lacked the red background. So at least most of the tables are more accessible and consistent. There is some wizardry that I don't understand going on with the Data Engineering section, so I couldn't fix the cell background color in those tables.
- Date format: n/a (reviewed)
- Extra item: Tables: Tables should not have empty columns. Fixed :-)
Writing style review
This page is a bit non-standard in that it's not really using prose or complete sentences in many of the table cells, which is fine, but it renders some of the standard style checklist items less relevant.
- Plain language: This page is full of technical jargon, but that's actually WAI. I reviewed for and removed some overly-casual phrasing.
- Positive language: Removed some negative or ambiguous text.
- Inclusive language: Checked; no changes needed.
- Active voice and verb mood: Updated as many instances as possible to consistently use third person present verbs to begin each description of what a given tool/component does, without using pronouns or unnecessary formulations like "A tool that does xyz" (instead, simply "Does xyz").
- Second person point of view: Checked, no changes needed.
- Typos: The page has been reviewed for typos.
Recommendations
In addition to addressing any outstanding items in the checklist, what are the most impactful changes that can be made to improve the page? If the page is part of a collection, what are the most impactful changes that can be made to improve the collection as a whole?
- Remove content in the intro section: limit it only to the minimum definitions of terms and instructions about when/how to add yourself as a maintainer etc. Remove the "Code Stewardship Coverage" graphs and put them somewhere more appropriate, like https://www.mediawiki.org/wiki/Code_Stewardship
- Clarify audience: Based on the Talk page history, it seems that WMF staff care about the contents of this page, and volunteers may not be aware of its existence. The intro section for the page should clearly state its intended audience(s) and probably also make it clear when/why users with given roles should edit the page.
- Clarify purpose: This page implies that it would be useful as a "who to contact to get help" directory, but that may be misleading. The lack of consistent page maintenance may lead readers to a dead end, or simply get them excited about having found such a useful resource...only to discover that it's incomplete.
- To reduce some user frustration, the page should include a section (probably at the top) that directs users to more reliable ways to get help, even if that help may not be specific to a given piece of code, some help is better than reaching out to an expert who is no longer active.
- Ensure utility / coverage: Once the purpose and audience of this page are clearer, it will be easier to determine who and how to maintain it. If it can't be maintained, it should potentially be archived in favor of other mechanisms for assigning or tracking code ownership / stewardship (For example, if the purpose of this page is to make it easier for volunteers to identify who to send code to for review, other efforts may more effectively address that: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/745946)
Maintainer outreach
Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.
*Covered in my comments above
Who seems to be active on or knowledgeable about the page?
- jbranaa (WMF), aklapper (WMF), bdavis (WMF)
Do the recommendations from this review include changes to the page title or other significant content changes and should be discussed with a maintainer?