Page MenuHomePhabricator

Proposal: Documentation improvements to the ~20 top 70 most-viewed MediaWiki Action API pages, Outreachy Round 18
Closed, ResolvedPublic

Description

Proposal for T215682

Profile Information

Name: Jerop Brenda
IRC nickname on Freenode: brendajerop
Web Profile: https://brendajerop.github.io
Blog: https://medium.com/@brendajerop2
Resume: https://www.resume.com/share/brendajerop
Location: Kenya
Typical working hours: 8:00 AM to 7:00 PM EAT (UTC+3)


Synopsis

1. Summary of the project

The MediaWiki Action API is a REST API that provides access to wiki features like creating an account, logging in, creating and editing a page, searching for a title and many more. A complete description is available here.
This project aims to improve the documentation of the API by re-writing it to follow this template and adding code samples to demonstrate the use of the API modules. A demo app based on some of the modules will also be created and a tutorial to explain its implementation will be written. The complete description of this project is available at T215682

Demo app

My idea for the demo app is an app that fetches the day’s holidays and observances from Wikipedia as shown here. This idea and its implementation will be subject to change as seen fit by the project mentors.

Features
  • Fetch the day’s holidays and observances using API:Parse and list them.
  • Allow searching for holidays by date.
  • Users can log in to add a new holiday. This will make use of API:Assert to check whether the user is logged in. If not, use API:Login to log the user in then use API:Edit to add a new holiday.
Implementation
  • I will use Python, Flask, HTML, CSS and Jinja templating.
  • The app will follow Wikimedia’s design principles and will assume a mobile layout. This is because the app's screens will not have a lot of content hence it will be a better use of space to have the app occupy a smaller area of the screen. Following a Mobile-First design will also ensure that the app looks and functions well on all platforms with the least amount of code. Having less code will ensure that the tutorial stays simple since it's mostly targeted at beginners.
Prototypes

2. Benefits of the project

By following a template, consistency will be achieved in the documentation. This provides a uniform way to give information hence making the use of the API more intuitive to new users. It also makes it easier for new contributors to understand how to edit and add new information.
Adding code samples and creating a demo app based on the modules will provide a practical means of understanding the API. This is especially important to new users and to users whom the documentation has not been translated into their language.


Possible Mentors

Srishti Sethi @srishakatux, Sarah R. Rodlund @srodlund.


Deliverables

1. Timeline

Before interns are announced: Today to May 6

  • Complete the tasks which are a work in progress and work on new tasks as I go through the tutorials at API:Main_page in order to improve my Python, Flask, HTML and CSS skills.

Before the internship starts: May 6 to May 20

  • Create a spreadsheet to analyse and document the state of the 50th to the 77th most-viewed pages as shown in Massviews Analysis in order to determine the amount of work needed in each page and the order of the pages to be edited.
  • Refine my ideas for the demo app and document my progress here.

May 20 to July 22 (9 weeks)

  • Improve the documentation of two API modules per week for a total of at least 20 modules at the end of the 9 weeks . The process followed each week will be similar for each module, i.e:
    • Create a separate git branch for the module, write sample code, commit it and open a pull request on GitHub for review.
    • Implement the requested changes if any as I work on the respective documentation of the module in my wiki sandbox.
    • Once the pull request is merged, I will integrate the sample code into the documentation.
    • Once the documentation is ready, I will send it to the mentor for review and implement any feedback received.
    • After the documentation has been approved by the project mentor, I will integrate it into the main-space and mark it as modified on T198916.
  • Finalize on demo app idea and mock-ups.

July 22 to July 30 (Week 10)

  • Start working on the demo app.
  • Write the base classes which will be extended by the specific feature classes. This is because some of the app's features will have a slightly similar layout and functionality.
  • Implement "List Holidays" feature, test it and include instructions for its implementation in a draft of the app's tutorial in my sandbox.
  • Submit the app to the project mentor for review and implement any feedback received.

At the end of week 10, the most basic and working version of the app will be complete.

July 30 to August 6 (Week 11)

  • Implement "Search Holidays by Date" feature, test it and include instructions for its implementation in a draft of the app's tutorial in my sandbox.
  • Implement "Logging in" feature, test it and include instructions for its implementation in a draft of the app's tutorial in my sandbox.
  • Submit the app for review and implement any feedback received.

August 6 to August 13 (Week 12)

  • Implement "Add New Holiday" feature, test it and include instructions for its implementation in a draft of the app's tutorial in my sandbox.
  • Submit the app for review and implement any feedback received.
  • Make any required improvements and fix any bugs that may have arised.

At the end of week 12, the app will be complete with all the intended features.

August 13 to August 20 (Week 13)

  • Refine the app's tutorial and send the final draft to the mentor for review.
  • Once the draft has been approved, I will include it in the tutorials section of API:Main_page and prepare it for translation.

August 20 onwards

  • Keep contributing to Wikimedia and volunteer as a mentor for Google Code-in.

Participation

  • I will communicate my progress to my mentor and ask for help on project-related issues through Zulip on the mediawiki-api-documentation-project stream.
  • I will ask for help on API-related issues on the Wikimedia Developer Support channel.
  • Throughout the internship period, I will document detailed progress through weekly blog posts on my blog.

About Me

  • I joined the University of Nairobi, Kenya, in 2015 to pursue Electrical and Electronic Engineering but took a year off in September 2018. On my first holiday from college, I attended a boot camp where I learnt Java and got introduced to Android Programming. On completion, I became a part of NaiCode, a community that teaches programming to high school students in Kenya.

    I later got selected for the Google Africa Scholarship Program to learn Intermediate Android Development. During that period, I also served as a community mentor to guide the beginner students through their Android Development course. My certificates for participation as a student and as a mentor are available here and here respectively.

    In August 2018, I applied to Y Combinator’s Startup School and luckily, all the companies that applied were accepted for that cohort. My Startup School profile is available here.
  • How did you hear about this program? I learnt about this program through Twitter, on a previous participant’s timeline.
  • Will you have any other time commitments, such as school work, another job, planned vacation, etc, during the duration of the program? No, I will not have any other time commitments during the duration of the program.
  • We advise all candidates eligible for Google Summer of Code and Outreachy to apply for both programs. Are you planning to apply to both programs and, if so, with what organization(s)? I took a year off from school so I will not be able to apply for Gsoc this round.
  • What does making this project happen mean to you? As an avid user of FOSS(I use Linux, Firefox, LibreOffice and VLC), this project provides a platform through which I can give back to FOSS because most open-source organisations use MediaWiki-powered wikis. It will also grant me a good entry point into open-source contribution.

    This project will also boost my skills, improve my confidence and shape me as a programmer. This is because I will be working in a mentored environment with a structured workflow where proper code documentation, organization, testing and coding styles need to be followed. Also, I love both writing and programming, and this project is a bridge between the two.

Past Experience

1. Contributions to Wikimedia

Microtasks

  • API:Querypage: Improved the documentation and wrote sample code to demostrate its use in querying uncategorized pages.
  • API:RecentChanges: Improved the documentation and wrote sample code to demostrate its use in fetching the three most recent changes with their sizes and flags.
  • API:Links: Wrote sample code to demonstrate its use in fetching missing links from a page. I also added this example to the documentation.

Documentation and API-related

  • I documented the undocumented classes in Addwiki's mediawiki-api library: T145376 The different classes use different API modules hence I interacted with their corresponding MediaWiki API modules in order to have a better understanding of how the classes work. As a result, I got to understand how to use these API modules. The classes which I documented are:
    • LogListGetter Merged: Gets all logged events in a wiki by using API:Logevents.
    • UserGetter Merged: Gets information about a user in a wiki by using API:User .
    • RevisionUndoer Merged: Undoes a certain revision in a wiki by using the "undo" parameter of API:Edit.
    • RevisionRollbacker Merged: Reverts the last series of edits made to a wiki page by using API:Rollback.
    • RevisionDeleter Merged: Deletes the content of a revision by using the hide parameter of API:Revisiondelete.
    • RevisionRestorer Merged: Restores content that has been revision-deleted by using the show parameter of API:RevisionDelete.
    • RevisionPatroller Merged: Patrols a revision by using API:Patrol.
    • RevisionSaver Merged: Saves edits to a revision by using API:Edit.
    • UserCreator Awaiting Review: Adds a new user to a wiki by using API:Account creation.
    • UserBlocker Awaiting Review: Blocks a user by using API:Block.
    • UserRightsChanger Awaiting Review: Changes the group membership of a user by using API:Usergroup membership.
  • I corrected the auto-generated documentation for parameter headhtml in module parse: T139567 Merged. When starting to work on this task, I wasn't sure if I was editing the correct file so I set up a local MediaWiki instance in order to confirm if the changes to the code were reflected on the wiki. Having a local MediaWiki instance later came in handy while working on tasks which required a wiki user to have admin or bureaucrat permissions. For instance when trying to create a test account on Wikipedia via the API, the limit per IP address is 6 trials in 24 hrs but with a local MediaWiki instance, I could raise the limit. In some cases, the documentation includes examples which have API parameters that are introduced by extensions(e.g OpenID). In this case having a local MediaWiki instance where I could install the extensions was helpful.
  • I included links of the corresponding API modules in Pywikibot methods.: T100521 Merged. I modified the docstrings of all APISite methods in site.py which are thin wrappers around a MediaWiki API module to include a link to the corresponding API documentation. Working on this task helped me discover more MediaWiki API modules and what they do. I also learnt how to write docstrings in Epytext format.
  • I documented Special:MergeHistory: T195271 Merged. While working on this page, I got to improve my documentation and wiki markup skills. I also got a better experience in working with translatable pages.
  • I documented the batchcomplete element of the MediaWiki Action API: T84977 Awaiting review. Working on this task helped me get a deeper understanding of the API and also improved my technical documentation and wiki markup skills. I queried several modules in several ways, e.g using them as a generator or as a property submodule in order to find cases where the batchcomplete element was not returned. As a result, I learnt a lot about generators, property submodules and how to use continue until the batchcomplete element is returned. I also learnt that batchcomplete is meant for modules which are submodules of the query module.

Other

2. Contribution to open source

The Mifos Initiative

3. Other projects

Python

  • Holidays Viewer- A web-app that fetches the current day’s holidays and observances from Wikipedia using API:Parse and lists them. I created this app in order to practise building the demo app and to refresh my Python, Flask, HTML and CSS skills. While working on the app, I learnt about and followed Wikimedia’s design principles in regards to colours, typography and visual style.
  • A simple school system app- A Flask CRUD web app that allows creation, editing and deletion of student data. This app was created as part of a group assignment at school. While working on this app, I got introduced to Python, Flask, HTML, CSS and SQL.
  • Simple blog-I created a simple blog while learning how to use Django at a Django Girls event.

Android

  • Github-Repos- An app that fetches a users repositories using the GitHub API. Working on this app helped me understand how APIs work, specifically REST APIs.
  • HideContacts-A contacts app that can’t be read by other apps. It doesn’t save contacts in vcf format so other apps like Whatsapp and Facebook don’t recognize it as a contacts app and hence they can’t read contacts from it. This improves privacy. I created this app after completing YC’s Startup School program where I learnt about concepts like Key Performance Indicators and Lean Software Development. The app currently has 1000+ users.
  • Orodha- An app that simplifies the process of creating an exam merit list for Kenyan teachers who don’t have access to computers.
  • TicTacToe- An Android version of Tic Tac Toe. I created this as a capstone project for an Android development course.
  • Goodnight- An android app to auto-send a goodnight message to specific people at a specific time

Java

I created these apps during a hackathon to demonstrate the usage of the Java GUI.

  • Screensaver- An app that creates wallpapers and screensavers by drawing spirographs on the screen.
  • Paint app- A painting app that allows you to paint on a screen by dragging the mouse. You can also change the colour of the pen, the background colour and the thickness of the pen.
  • Touch-type Practice- An app that allows you to practise touch-typing by giving you a word to type against a set time limit. It has a virtual keyboard on the screen that highlights any key pressed.
  • Animated-card- An animated get-well-soon card with background music.

Matlab

  • Medical-Diagnosis- An app to diagnose lifestyle diseases using Matlab’s Neural Network Toolbox. I created this app as a requirement of a class assignment.

Related Objects

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 11 2019, 4:35 PM
jeropbrenda renamed this task from Oeutreachy Round 18: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wikirt project title here to Outreachy Round 18: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wikirt project title here.Mar 11 2019, 4:36 PM
jeropbrenda renamed this task from Outreachy Round 18: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wikirt project title here to Outreachy Round 18: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wiki.
jeropbrenda renamed this task from Outreachy Round 18: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wiki to Proposal: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wiki- Outreachy Round 18.
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 9:16 AM
jeropbrenda added subscribers: srishakatux, srodlund.
Restricted Application added a subscriber: Liuxinyu970226. · View Herald TranscriptMar 17 2019, 9:16 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 9:39 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 10:17 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 10:28 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 10:33 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 11:21 AM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 12:53 PM
Restricted Application added a subscriber: MusikAnimal. · View Herald TranscriptMar 17 2019, 12:53 PM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 1:00 PM
jeropbrenda updated the task description. (Show Details)Mar 17 2019, 1:13 PM
jeropbrenda updated the task description. (Show Details)Mar 18 2019, 6:35 AM
jeropbrenda updated the task description. (Show Details)
jeropbrenda renamed this task from Proposal: Documentation improvements to the ~20 top 70 most viewed MediaWiki Action API pages on-wiki- Outreachy Round 18 to Proposal: Documentation improvements to the ~20 top 70 most-viewed MediaWiki Action API pages, Outreachy Round 18.Mar 18 2019, 6:38 AM

@srishakatux Here is the first draft of my proposal. Would love your feedback. Thanks:)

jeropbrenda updated the task description. (Show Details)Mar 18 2019, 6:56 AM

@jeropbrenda Your proposal looks great!! You've covered all the points and I don't have recommendation for more changes that you could add. Whenever you are ready, you can submit your proposal on the Outreachy site and move it to the "Proposals Submitted" column on the Outreachy (Round 18) workboard in Phabricator.

@srishakatux Thank you so much for the feedback!

jeropbrenda updated the task description. (Show Details)Mar 20 2019, 10:05 AM

sorry for moving your task by mistake :)

jeropbrenda updated the task description. (Show Details)Mar 26 2019, 3:50 PM
jeropbrenda updated the task description. (Show Details)
jeropbrenda updated the task description. (Show Details)Mar 30 2019, 10:57 AM
jeropbrenda updated the task description. (Show Details)Apr 1 2019, 9:26 AM
jeropbrenda updated the task description. (Show Details)Apr 1 2019, 9:29 AM
jeropbrenda updated the task description. (Show Details)Apr 1 2019, 3:53 PM
jeropbrenda updated the task description. (Show Details)Apr 3 2019, 6:55 PM
jeropbrenda updated the task description. (Show Details)Apr 3 2019, 7:05 PM
jeropbrenda updated the task description. (Show Details)Apr 4 2019, 8:23 PM
jeropbrenda updated the task description. (Show Details)Apr 6 2019, 5:14 AM
jeropbrenda updated the task description. (Show Details)Apr 7 2019, 6:26 AM
jeropbrenda updated the task description. (Show Details)Apr 7 2019, 2:55 PM
jeropbrenda updated the task description. (Show Details)Apr 8 2019, 5:41 AM

Initial feedback update: I've improved 9 pages in my sandbox, and seven of them have been merged to the main namespace. More detailed information available at https://www.mediawiki.org/wiki/User:Jeropbrenda#Project_Outcomes

Congratulations on completing the project! If there isn't anything remaining in your proposal to address, feel free to close this task. Before you do so, make sure your project is listed here https://www.mediawiki.org/wiki/Outreachy/Past_projects and has the following information: Student name, Mentors, Relevant links and Outcomes (in not more than two lines). Thank you for your participation!

jeropbrenda closed this task as Resolved.Sep 4 2019, 4:54 PM
jeropbrenda updated the task description. (Show Details)