Grants:Project/Jayprakash12345/Improve documentation of MediaWiki maintenance scripts

statusselected
Improve documentation of MediaWiki maintenance scripts
summaryThis project is about to improve the documentation of MediaWiki maintenance scripts on MediaWiki.Org.
targetMediaWiki
type of grantsoftware
amount9350 USD
granteeJayprakash12345
advisorAPaskulin_(WMF)
contact• 0freerunning(_AT_)gmail.com
this project needs...
volunteer
organization
grantee
contact
join
endorse
created on05:56, 16 March 2021 (UTC)


Project idea

edit

What is the problem you're trying to solve?

edit

This project is about to improve the documentation of MediaWiki maintenance scripts on MediaWiki.org. There are almost 200+ maintenance scripts. Out of 200+, 125 scripts need to document. There are 42 scripts that only have a predefined template and 43 scripts that only have predefined template + one-line descriptions. MediaWiki maintenance scripts play a vital role in wiki maintenance. According to WikiApiary, There are 21647 standalone wikis and it is painful for the sysadmin to reading documentation from the docstring of the script file before running the maintenance script. Lack of documentation can cost to site down for some time. MediaWiki.org is the primary source to provide these kind of basic support. According to MassViews this year, There are 287 views per day on maintenance script pages. So it becomes important to document them on MediaWiki.org.

Last years MediaWiki maintenance scripts traffic stats (Total: 105,125; 287/day)
 

Source: https://pageviews.toolforge.org/massviews

What is your solution to this problem?

edit

Under this project, I will create a format/structure with minimum sections like Details, Usage, Parameter/Options, and Troubleshooting with templates and document the maintenance scripts. Documentation of the maintenance script will directly benefit the MediaWiki users, developers and sysadmins.

Project goals

edit
  • Creating a format/structure with minimum sections like Details, Usage, Parameter/Options, and Troubleshooting.
  • Creating templates for maintenance script documentations
  • Expanding scripts having an only predefined template
  • Expanding scripts having predefined template + one-line description
  • Expanding scripts having predefined template + one-line description + outdated template
  • Expanding/Improving other scripts

Project impact

edit

How will you know if you have met your goals?

edit

When scripts mentioned below will

  • have at least 3000 bytes of size
  • have section Details which provide introduction and use case of the script
  • have section Usage which provide details of running the script
  • have section Parameter/Options which provide details about parameters which can be used with the script
  • have section Troubleshooting which provide details common issues raise during running the script
  • have structured templates.

For statistics, I will deploy and enable wikitech:MediaWiki:Gadget-userfeedback.js for maintenance script page.

Project plan

edit

Activities

edit

I have categorised the documentation in four parts.

  1. Scripts with only predefined template (mw:Template:MW file); this templates is only a informative box about files in MediaWiki core
  2. Scripts with predefined template and having one line description
  3. Scripts with predefined template and having one line description & outdated template
  4. Scripts need to be expand (which does not fall in above categories but still need to improve)

I will document these four category of MediaWiki maintenance script one by one.

Scripts with only predefined template (Total: 42)
addRFCandPMIDInterwiki.php addSite.php categoryChangesAsRdf.php checkDependencies.php
cleanupRevActorPage.php deduplicateArchiveRevId.php deleteAutoPatrolLogs.php deleteTag.php
exportSites.php findDeprecated.php findMissingFiles.php findOrphanedFiles.php
generateSchemaSql.php importSites.php initUserPreference.php invalidateUserSessions.php
manageJobs.php migrateFileRepoLayout.php migrateImageCommentTemp.php mysql.php
populateInterwiki.php populateIpChanges.php populatePPSortKey.php purgeModuleDeps.php
resetPageRandom.php tidyUpT39714.php updateCredits.php uppercaseTitlesForUnicodeTransition.php
cleanupBlocks.php cleanupInvalidDbKeys.php deleteLocalPasswords.php dumpCategoriesAsRdf.php
fixDefaultJsonContentPages.php generateLocalAutoload.php makeTestEdits.php manageForeignResources.php
populateArchiveRevId.php populateExternallinksIndex60.php refreshExternallinksIndex.php renameRestrictions.php
validateRegistrationFile.php getReplicaServer.php - -


Scripts with predefined template + one line description (Total: 43)
populateFilearchiveSha1.php populateImageSha1.php populateLogSearch.php renameDbPrefix.php
runBatchedQuery.php syncFileBackend.php updateRestrictions.php cleanupRemovedModules.php
cleanupTable.inc checkBadRedirects.php checkLess.php compareParserCache.php
convertUserOptions.php copyFileBackend.php copyJobQueue.php deleteSelfExternals.php
userDupes.inc fileOpPerfTest.php findHooks.php fixExtLinksProtocolRelative.php
formatInstallDoc.php getSlaveServer.php importSiteScripts.php jsparse.php
mcc.php mctest.php mergeMessageFileList.php mwdoc-filter.php
patchSql.php populateBacklinkNamespace.php populateRecentChangesSource.php populateRevisionLength.php
populateRevisionSha1.php preprocessDump.php preprocessorFuzzTest.php protect.php
view.php purgeChangedFiles.php refreshFileHeaders.php initEditCount.php
pruneFileCache.php populateContentTables.php populateLogUsertext.php -


Scripts with predefined template + one line description + outdated template (Total: 8)
purgeChangedPages.php doMaintenance.php dumpIterator.php dumpLinks.php
checkComposerLockUpToDate.php compareParsers.php fixTimestamps.php getConfiguration.php


Scripts need to expand (Total: 31)
attachLatest.php checkImages.php checkUsernames.php cleanupWatchlist.php
clearInterwikiCache.php createCommonPasswordCdb.php deleteDefaultMessages.php deleteOrphanedRevisions.php
dumpTextPass.php eraseArchivedFile.php fixUserRegistration.php minify.php
nukePage.php orphans.php populateCategory.php populateParentId.php
purgeExpiredUserrights.php purgeExpiredWatchlistItems.php rebuildImages.php rebuildmessages.php
refreshImageMetadata.php removeUnusedAccounts.php showSiteStats.php sql.php
sqlite.inc updateArticleCount.php updateCollation.php updateDoubleWidthSearch.php
updateExtensionJsonSchema.php wrapOldPasswords.php deleteBatch.php -


I will follow mw:Documentation/Technical documentation templates and suggestions and mw:Documentation/New technical writers created by User:SRodlund (WMF).


Budget

edit

I will document the maintenance script as technical writer for 350 hours.

  • Technical writer: 350 * $25 = $8750
  • Internet: $200
  • Bank charges and contingency: $400

Total: 9350 USD

Community engagement

edit
  1. I will setup the mw:Project Pralekhan page at MediaWiki.org on which any community member can watch the page and comment on talk page.
  2. After completing 5-8 script, I will do the video call to User:SRodlund (WMF) and User:APaskulin (WMF) for their feedback
  3. When I will get thumb up from User:SRodlund (WMF) and User:APaskulin (WMF) then I will do video call with larger MediaWiki community for their inputs. I will do two more video call to community members during mid and end of project.
  4. I will post regular updates to MediaWiki-l, MediaWiki-India, and Wikitech-l mailing list and MediaWiki village pump.

Other FAQ

edit
What are your thoughts on the discoverability of maintenance scripts?

Manual:Maintenance scripts is the current main page for maintenance scripts. But it looks like that everything has put on this single page. This single page contains Introduction, configuration, running the scripts, list of maintenance scripts sections. It needs major improvement. I will work on the following 3 ways to improve discoverability.

  1. Improvement on the Main page :- In this part, I will divide the Manual:Maintenance_scripts page into subpages and create the sidebar just like others did for API:Main page and Manual:Pywikibot in the past. It will create a new room to expand the current section in the subpages. Ex. `Running the scripts` section can expand more on their subpage.
  2. Categorisation of scripts:- As a Wikipedia reader and MediaWiki contributor, I find myself that Category is the most effective way of discoverability. Reading about Space Rocket on Wikipedia? Just go to the bottom of the page, You will find categories like Rockets by NASA, Rockets in 1980, etc. Just like that, Categories do their job on MediaWiki as well. I found some of the scripts don't even have a base category (Category:Maintenance_scripts). Examples are categoryChangesAsRdf.php and cleanupRevActorPage.php. So in this part, I will categorize the scripts on their nature. Some natures are already listed on Manual:Maintenance_scripts#List_of_maintenance_scripts like language, storage, and term. I will create the categories on the basis of nature. and add them to the script accordingly. So it will improve the discoverability of maintenance scripts a lot for system admins.
  3. Interlinking of docs:- In this part, I will improve the See also or Related links sections. As having MediaWiki experience, I can wikilink the relevant page to scripts pages. Like I linked Extension:BlockAndNuke and Extension:BlockBatch to mw:Manual:blockUsers.php page. Another example is if there will be any script that needs to encourage Backup before running the script. then I will add the Manual:dumpBackup.php and Manual:Backing up a wiki link.
Are there any maintenance script docs that you can point to as examples of the level of documentation you'd like to achieve for other scripts?

Yes, these are some of the scripts that have a good level of documentation. But most of them are unstructured and inconsistent. I would like to achieve at least the same level of documentation. But in a structured and consistent way.

  1. mw:Manual:Update.php
  2. mw:Manual:ImportImages.php
  3. mw:Manual:ImportDump.php
  4. mw:Manual:MoveBatch.php

Get involved

edit

Participants

edit
  • Jay Prakash - I have been a Wikipedian since 2015 and Wikimedia technical contributor since early 2017. I joined the Wikimedia world in 2015 from English Wikipedia and then regularly contribute to my native wiki (Hindi Wikipedia) since 2016. But After knowing MediaWiki, I shifted my contribution in MediaWiki Extensions Maintenance and development since early 2017. I had uploaded around 556 patches on Gerrit where 512 patches already merged in the Wikimedia repository. I am a Technical resource person/trainer of many offline Indic Wikimedia programs. My past activity can be tracked by the following.
  1. Wikimedia Intern for Google Summer of Code 2019 for MediaWiki API (31 commit) documentation
  2. Created tabbed window OOUI widget, which is used by MediaWiki.org Community for API documentation.
  3. 512 patches out 556 have been merged at Gerrit Wikimedia.
  4. 60+ commit on Indic-TechCom’s Github repo.
  5. Created 7 Userscripts and 8 Toolforge tools for Wikimedia communities
  6. Technical resource person in three Wikimedia workshop
  7. MediaWiki trainer in three MediaWiki training India events
  8. Co-organiser and mentor of Small wiki toolkits – Indic workshop series 2020 and Small wiki toolkits‎ - South Asia 2021
  9. Volunteer developer of Indic-TechCom from 2018
  10. Helps community using Global Interface rights
  11. Created Wikisource Dedicated Python API library pywikisource python library during Wikimania 2019.
  12. Past technical documentation phab:T217991, phab:T254081, phab:T257654, phab:T215681, phab:T188892, and phab:T218417.

Community notification

edit

Endorsements

edit

Do you think this project should be selected for a Project Grant? Please add your name and rationale for endorsing this project below! (Other constructive feedback is welcome on the discussion page).

  • This would be really useful! One thing I'd like to suggest is to try to assess if the script is still used or valid, some of these maintenance scripts are old and might not be usable anymore. KHarlan (WMF) (talk) 13:39, 7 April 2021 (UTC)
  • I also support this initiative. And I believe that there needs to be some technical component to test the scripts for functionality because like KHarlan mentions some of the scripts may not be usable anymore. GregRundlett (talk) 22:05, 7 April 2021 (UTC)
  • +1 --BDavis (WMF) (talk) 16:30, 8 April 2021 (UTC)
  • I believe this is a solid proposal and would be a beneficial contribution to Wikimedia technical projects. SRodlund (WMF) (talk) 17:22, 8 April 2021 (UTC)
  • As the advisor, I support this project. It's well-scoped and will have a positive impact on MediaWiki developers and admins. APaskulin (WMF) (talk)
  •   Support -- Regards, ZI Jony (Talk) 14:03, 9 April 2021 (UTC)
  •   Support -J. Ansari Talk 17:06, 9 April 2021 (UTC)
  • This is a great initiative. Jdforrester (WMF) (talk) 21:36, 10 April 2021 (UTC)
  •   Support -- CAndrew (WMF) (talk) 15:49, 16 April 2021 (UTC)
  •   Support thanks for taking this on! Legoktm (talk) 02:43, 19 April 2021 (UTC)
  •   Support Nice idea. Leaderboard (talk) 07:52, 19 April 2021 (UTC)
  •   Support * Pppery * it has begun 16:57, 23 April 2021 (UTC)
  •   Support, good to see this project. Good luck. Kind regards, — Tulsi Bhagat contribs | talk ] 08:20, 8 May 2021 (UTC)
  •   Support I'm late but just to say that's great --Valerio Bozzolan (talk) 08:27, 25 February 2022 (UTC)