Page MenuHomePhabricator

GSoD 2020 Proposal: Improve documentation of MediaWiki maintenance scripts
Closed, DeclinedPublic

Description

Profile Information

Name: Jay Prakash
IRC nickname on Freenode: Jayprakash12345
Gmail ID: 0freerunning@gmail.com
GitHub profile: https://github.com/Jayprakash-SE/
Gerrit Profile:: https://gerrit.wikimedia.org/r/#/q/owner:0freerunning@gmail.com
Location: India
Typical working hours: 5:00 PM to 1:00 AM UTC +5:30

Synopsis

Project summary

  • 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 soon. There are 46 scripts that only have a predefined template. and 40 scripts that only have predefined + 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. And lack of documentation can cost to site down for some time. MediaWiki.org is the primary source to provide this kind of basic support. According to MassViews this year, There are 296 views per day on maintenance script pages. So it becomes important to document them on MediaWiki.org. Documentation of the maintenance script will directly benefit the 21647 standalone wiki's sysadmins. 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.
This year - 45,347 (296/day)
Last year - 117,376 (322/day)

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

Scripts with only predefined template

Total count:- 46

Scripts with predefined template + one line description

Total count:- 40

Scripts with predefined template + one line description + outdated template

Total count:- 8

Scripts need to expand

There are 31 maintenance scripts that need to expand. They are lack of minimal sections like usage, parameter/options, troubleshooting. 2 of them have outdated template.

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 outreachy intern 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.
  1. Categorization 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 findBadBlobs.php, 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.
  2. Interlinking of docs:- In this part, I will improve the See also or Related links sections. As having some mediawiki experience, I can wikilink the relevant page to scripts pages. Like I linked Extension:BlockAndNuke and Extension:BlockBatch to 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.

Apart from it, I will post work on marking the page for translations through Translation Extension. I am not including it in the proposal. But willing to work.

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. https://www.mediawiki.org/wiki/Manual:Update.php
  2. https://www.mediawiki.org/wiki/Manual:ImportImages.php
  3. https://www.mediawiki.org/wiki/Manual:ImportDump.php
  4. https://www.mediawiki.org/wiki/Manual:MoveBatch.php

Possible Mentor(s)

Deliverables

  • 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
  • Marking pages for translation

Participation

  • I will be online on IRC in my working hours ( 5:00 PM to 1:00 AM +5:30) to collaborate with the mentors. I have IRC/Cloaks with the name wikimedia/Jayprakash12345.
  • Communication with my mentors will be done via Zulip/IRC during working hours.
  • I will be available in non-working hours through my Google mail account.
  • I will use wiki-markups instead of HTML
  • I will use wiki-table to track every script's documentation quality.

About Me

I am a 2nd-year student of Bachelor of Technology (Computer Science & Engineering). My University is Dr. A.P.J. Abdul Kalam Technical University. I have programming experiences for more than 5 years as I had computer science as my stream during High-School. I have been a Wikipedian since 2015. and Wikimedia technical contributor since early 2017. This is my first time applying for the Google season of docs.

How did You hear about this Program ?

I heard about this program for the first time in the Wikimedia world last year. when I kept my eyes on the phabricator task for the new bug. Then I eagerly researched on Google season of docs.

Will you have any other time commitments, such as school work, another job, planned vacation, etc, during the duration of the program?

I will have my unit tests exam during the duration of the program. Otherwise, I do not have any other time commitments.

Are you planning to apply with other organization(s) and, if so, with what organization(s)?

I am only applying to Google Season of Docs with the Wikimedia Foundation. This will be the only proposal.

What does making this project happen to mean to you?

It matters a lot to me. I am very enthused about the free open-source software. In the Wikimedia world, I am getting this great chance to contribute to FOSS. From this project, I will deeply drive into the technical documentation. and will start contributing to documentation apart from fixing the bug and developing the tool. Overall this project will boost my activity a lot in the Wikimedia world.

Timeline

PeriodTask
August 17 - September 13Community bonding period - Get in touch with the mentors and discussion on the documentation format and structure in detail. Creating the required template with good UI.
September 14 - September 20Week 1 - Documentation of scripts having only predefined template 1-12
September 21 - September 27Week 2 - Documentation of scripts having only predefined template 13-24
September 28 - October 04Week 3 - Documentation of scripts having only predefined template 25-36
October 5 - October 11Week 4 - Documentation of scripts with having predefined template 36-46
October 12 - October 18Week 5 - Documentation of scripts having predefined template + one-line description 1-13
October 19 - October 25Week 6 - Documentation of scripts having predefined template + one-line description 14-27
October 26 - November 01Week 7 - Documentation of scripts having predefined template + one-line description 28-40
November 02 - November 08Week 8 - Documentation of scripts having predefined template + one line description + outdated template (all)
November 09 - November 15Week 9 - Documentation of scripts need to expand 1-15
November 16 - November 22Week 10 - Documentation of scripts need to expand 16-31
November 23 - November 29Week 11 - Improving currently expanded documentation
November 30 - December 5Final evaluations

Past Experience

I joined the Wikimedia world in 2015 from English Wikipedia. And 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 June 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 like MediaWiki Training 2018, MediaWiki Training 2019, Wiki Advanced Training 2018, NSCET MediaWiki Training, VVIT MediaWiki Training 2019, Jaipur Technical Training 2017, and Bhopal Technical Training 2018. My past activity can be tracked by the following.

Online Technical Contribution

  • Created Toolforge tools

Offline/Outreachy events

Community Engagement/Others

  • Volunteer Lead Developer of Indic-TechCom:- Primary responsible to create the new tool/reports/RfC and assist the Indic-Community (24 Languages with its project).
  • 19,000+ global wiki edits. My favorite wiki project is Wikiversity. I am a sysop at Hindi Wikiversity.
  • Heritage GLAM:- I have provided technical support to the Heritage GLAM Team. I have developed some tools under Heritage GLAM.
  • Technical advisor of many Indic community’s regional partnerships.
  • Maintain the Indic Wiki Gadgets and user scripts. See Indic-TechCom/Management for detailed Report.
  • Created Wikisource Dedicated Python API library pywikisource python library during Wikimania 2019.

Technical Documentation

Event Timeline

Restricted Application added a project: User-Jayprakash12345. · View Herald TranscriptJun 2 2020, 11:14 PM
Restricted Application added subscribers: MusikAnimal, Aklapper. · View Herald Transcript
Jayprakash12345 added subscribers: apaskulin, srodlund.
Jayprakash12345 renamed this task from [WIP] GSoD 2020 Proposal: Improve documentation of MediaWiki maintenance scripts to GSoD 2020 Proposal: Improve documentation of MediaWiki maintenance scripts.Jun 19 2020, 7:01 PM
Jayprakash12345 updated the task description. (Show Details)

@apaskulin @srodlund Please review the proposal.

Hi @Jayprakash12345! I think this is a great proposal. I like that you've chosen a well-defined, achievable scope and that you've included pageview data to demonstrate the impact. I agree that creating a standard template for maintenance script docs will be key to enabling this work and allowing it to continue and expand into the future.

I have a couple of questions that might be interesting to consider or include in your proposal:

  1. 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?
  2. What are your thoughts on the discoverability of maintenance scripts? You mention the importance of maintenance scripts to wiki admins; is there a way to improve the docs so that it's easier for admins to find the maintenance scripts they need?
Jayprakash12345 added a comment.EditedJun 23 2020, 7:10 PM

@apaskulin Thank you very much for reviewing.

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. https://www.mediawiki.org/wiki/Manual:Update.php
  2. https://www.mediawiki.org/wiki/Manual:ImportImages.php
  3. https://www.mediawiki.org/wiki/Manual:ImportDump.php
  4. https://www.mediawiki.org/wiki/Manual:MoveBatch.php

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 outreachy intern 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.
  1. Categorization 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 findBadBlobs.php, 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.
  2. Interlinking of docs:- In this part, I will improve the See also or Related links sections. As having some mediawiki experience, I can wikilink the relevant page to scripts pages. Like I linked Extension:BlockAndNuke and Extension:BlockBatch to 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.

Apart from it, I will post work on marking the page for translations through Translation Extension. I am not including it in the proposal. But willing to work.

Eagerly wants to know if there are any other more effective may for discoverability. Thank you

@apaskulin @srodlund Hi, Please can you review the proposal again? If there is more room for improvement.

Thanks for making those updates, @Jayprakash12345! I think the proposal looks great. One possible typo I noticed: "But in a structured and inconsistent way."

Thanks for making those updates, @Jayprakash12345! I think the proposal looks great. One possible typo I noticed: "But in a structured and inconsistent way."

Thank you very much. I fixed the typo.

Jayprakash12345 closed this task as Declined.EditedAug 19 2020, 9:53 PM

The proposal did not get selected in GSoD.

@apaskulin and @srodlund Thank you very much for the proposal assessment.

Just curious to know, Was proposal not viable for GSoD? or rejected due to conflict of interest. In the same year, GSoC rejected me too, and the reason was "I am over-qualified and working with the organization for a very long time".

srodlund added a comment.EditedAug 19 2020, 10:36 PM

@Jayprakash12345 Thanks for reaching out. Your proposal is solid, but we are only able to take on one participant this year. It's can be difficult to make decisions when there are a number of good proposals but limited spaces, and we have to weigh out a number of factors -- including candidate experience, and what how proposals fit into initiatives we're currently working on.

It would be really nice to see this proposal move forward as a volunteer project, even if it's not associated with a program like GSoD or GSoC. This may also be something we could bring to the Friends of the Docs discussion to see if there would be others interested in working with you on this. We're setting a date for a next live meeting soon and there is a Zulip stream for this. Another option may be to apply for a software grant: https://meta.wikimedia.org/wiki/Grants:Project I have been told that these will be opening up again in 2021.