Grants:Project/Jayprakash12345/Improve documentation of MediaWiki maintenance scripts
This project is funded by a Project Grant
| proposal | people | timeline & progress | finances | midpoint report | final report |
gmail.com
Project idea
editWhat is the problem you're trying to solve?
editThis 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.
|
Source: https://pageviews.toolforge.org/massviews
What is your solution to this problem?
editUnder 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
editHow will you know if you have met your goals?
editWhen 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.
- When mw:Manual:Maintenance scripts will have structured sidebar and sections for easy navigating.
For statistics, I will deploy and enable wikitech:MediaWiki:Gadget-userfeedback.js for maintenance script page.
Project plan
editActivities
editI have categorised the documentation in four parts.
- Scripts with only predefined template (mw:Template:MW file); this templates is only a informative box about files in MediaWiki core
- Scripts with predefined template and having one line description
- Scripts with predefined template and having one line description & outdated template
- 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.
| purgeChangedPages.php | doMaintenance.php | dumpIterator.php | dumpLinks.php |
| checkComposerLockUpToDate.php | compareParsers.php | fixTimestamps.php | getConfiguration.php |
I will follow mw:Documentation/Technical documentation templates and suggestions and mw:Documentation/New technical writers created by User:SRodlund (WMF).
Budget
editI 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- 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.
- After completing 5-8 script, I will do the video call to User:SRodlund (WMF) and User:APaskulin (WMF) for their feedback
- 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.
- 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.
- 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.
- 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.
- 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.
Get involved
editParticipants
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.
- Wikimedia Intern for Google Summer of Code 2019 for MediaWiki API (31 commit) documentation
- Created tabbed window OOUI widget, which is used by MediaWiki.org Community for API documentation.
- 512 patches out 556 have been merged at Gerrit Wikimedia.
- 60+ commit on Indic-TechCom’s Github repo.
- Created 7 Userscripts and 8 Toolforge tools for Wikimedia communities
- Technical resource person in three Wikimedia workshop
- MediaWiki trainer in three MediaWiki training India events
- Co-organiser and mentor of Small wiki toolkits – Indic workshop series 2020 and Small wiki toolkits - South Asia 2021
- Volunteer developer of Indic-TechCom from 2018
- Helps community using Global Interface rights
- Created Wikisource Dedicated Python API library pywikisource python library during Wikimania 2019.
- Past technical documentation phab:T217991, phab:T254081, phab:T257654, phab:T215681, phab:T188892, and phab:T218417.
Community notification
edit- MediaWiki-l (https://lists.wikimedia.org/pipermail/mediawiki-l/2021-April/048690.html)
- MediaWiki-India (https://lists.wikimedia.org/pipermail/mediawiki-india/2021-April/000113.html)
- wikitech-l (https://lists.wikimedia.org/pipermail/wikitech-l/2021-April/094409.html)
- MediaWiki village pump (https://www.mediawiki.org/wiki/Topic:W6mt0iex7z8zyk7f)
Endorsements
editDo 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)
