Page MenuHomePhabricator

Proposal: Improving ~20 documentation pages and creating a demo app to help users of MediaWiki learn how to use our APIs - Outreachy 17
Closed, ResolvedPublic

Description

Profile Information

Name: Marty Hernandez Avedon
Github: https://github.com/martyav
Web Profile: https://martyav.github.io/about-me/
Blog: https://martyav.github.io/blog-posts/
Resume: https://www.linkedin.com/in/marty-hernandez-avedon/
Location: New York, USA
Time Zone: EST (UTC -5:00)
Typical working hours: 10:30 am to 7pm

Summary

From the task description on Outreachy (https://www.outreachy.org/december-2018-march-2019-outreachy-internships/communities/wikimedia/#mediawiki-action-api-documentation-improvements-to):

The MediaWiki action API is a web service that allows access to some wiki-features like authentication, page operations, and search. It can provide meta information about the wiki and the logged-in user. Several Wikimedia projects make use of this API.

As of now, there are 128 pages part of the Action API on MediaWiki.org. We did a little research on the state of the docs and documented a few problems and recommendations for next steps. One of the issues we decided to address was inconsistency. For example, some pages had the automated API docs embedded; some didn’t, some pages had code samples, some didn’t, etc.

As a first step, we designed a documentation template and used it to re-write top 20 viewed pages of the API. But, we realized we cannot improve 128 pages all by ourselves, and for that we need your help! :-) As part of Outreachy, the goal of this project is to improve the next 30 viewed pages using the documentation template.

First Steps

So far, I have completed API:Images (https://www.mediawiki.org/wiki/API:Images) and API:Redirects (https://www.mediawiki.org/wiki/User:Martyav/API:Redirects), and have a draft in my sandbox for API:Lists (https://www.mediawiki.org/wiki/User:Martyav/Sandbox/API:Lists).

I have also contributed sample code (https://github.com/srish/MediaWiki-Action-API-Code-Samples/pull/9 & https://github.com/srish/MediaWiki-Action-API-Code-Samples/pull/17).

I would like to continue working on this task, as well as work on a Python-based web app demonstrating two or more APIs, so users of MediaWiki have a practical, working example of how to utilize our software.

Mentors

Sarah Rodlund (@srodlund) and Srishti Sethi (@srishakatux)
I have been in touch with Sarah Rodlund and Srishti Sethi since Outreachy approved me for contributing, in early October.


Deliverables

  • 2 to 3 articles per week, over the course of 10 weeks, for a total target of 20 completed articles.
  • 3 weeks on writing and testing a web demo with a Flask backend.
  • 12 blog posts, produced weekly, describing my progress

Before the program starts, I will, in preparation for the demo, study and practice Python and the Flask framework, which Sethi used in the demo app on her sample code repo (https://github.com/srish/MediaWiki-Action-API-Code-Samples/tree/master/demos/article%20suggestion). I will make at least one Python commit per day to my Github account (https://github.com/martyav) to track my progress on this.

For the first 9 weeks of the program, I will focus entirely on improving articles and creating sample code where needed. Starting on the 10th week, I will begin transitioning to work on a demo. By week 11 and 12, I will be entirely focused on the demo.

The demo will be designed to help users learn how to use our APIs. It will use multiple APIs to demonstrate their features. The demo will utilize, in part, Python code from Srishti Sethi's sample code repo (https://github.com/srish/MediaWiki-Action-API-Code-Samples/tree/master). I will also create tests to ensure code quality and effectiveness.

The demo will rely on as few dependencies as possible, to keep it light and evergreen, and have a GUI similar to a mobile app (articles presented in vertical lists, with a navigation menu always visible). This mobile-first design would reflect global demographics of smart phone usage (https://techcrunch.com/2016/11/01/mobile-internet-use-passes-desktop-for-the-first-time-study-finds/), and would also provide educational value to web/mobile students learning how to code via MediaWiki's APIs.

Need

An example of a tech education program using MediaWiki's APIs to teach students how to make web apps: https://learn.freecodecamp.org/coding-interview-prep/take-home-projects/build-a-wikipedia-viewer/

An example of two students frustrated with the current documentation, while attempting the project: https://www.reddit.com/r/FreeCodeCamp/comments/46me96/wikipedia_viewer/d0cmoga

Having clearly written docs and a sample app would ease the learning curve for beginners, as well as for experienced developers, hoping to use our APIs.


Participation

I would continue to communicate with Sethi on Phabricator and Zulip, and Rodlund via email. I would host my demo and any sample code on Github, in a fork of Sethi's sample code repo (https://github.com/martyav/MediaWiki-Action-API-Code-Samples).

Throughout the project, I will be writing weekly blog posts describing my work.


About Me

Prior to getting into tech, I wrote short web articles, and also created print work (flyers, pins, etc.) for nonprofits and local businesses. I liked what I was doing, but it wasn't well-paid, and I was having a hard time. I started learning how to code because I wanted to create a better life for myself.

I figured that once I had tech skills, I could still write and design, but the work would pay better and reach more people. The same month I was accepted into my tech bootcamp, I became homeless.

I'm doing better now -- I managed to graduate, tutor other students, and get an apprenticeship this spring. I am still trying to break into tech with a fulltime job, and to do that, I need to build a great portfolio and learn from more experienced developers.

Q. How did you hear about this program?
A. I learned about it on a tech Slack for LGBT people.

Q. Will you have any other time commitments, such as school work, another job, planned vacation, etc, during the duration of the program?
A. I like to tutor at my former bootcamp, but I can participate in helping students in other ways if I fall short of my timeline. I plan on taking November 22 off for Thanksgiving, and December 31 and January 1 off for New Years.

Q. What does making this project happen mean to you?
A. I like educating others. I want to make the API documentation easier to use in part because it is already being used by people like me -- students or alumni from bootcamps -- but sometimes it is confusing, and that hinders people from diverse backgrounds from learning and gaining tech skills.

I also enjoy writing, breaking down technical topics, and creating sample code. It makes me feel helpful to create resources that make it easier for people to understand tough or complicated subjects.

In addition, I want to improve my Python skills. I like Python, but I've never used it in a large project or app. I'd like to challenge myself by working on a demo app.

On a more personal level: I've been having a hard time finding mentorship in the tech community. I know it's really important to network and learn from more experienced developers, but I've been struggling to find that. Most of the people who have helped me along the way have come from similar backgrounds as I do, and don't have much more experience than I do myself. I'm interested in Outreachy because I want to grow and learn from others with much more experience, and from different backgrounds, in a welcoming environment.


Education

I studied graphic design at a city college in New York (Kingsborough). After graduating with an Associates in 2010, I started on my Bachelors in Media, but had to leave school before I could complete it. At that time, I was dealing with some heavy personal issues, such as the death of my father, and starting my medical transition as a trans person.

I spent several years (2010 to 2016) writing for OneSpace, a company that provides web articles for sites such as AskJeeves. I wrote on a large variety of topics, including computer science subjects ("What's a delimiter?") aimed at a middle school reading level.

I started teaching myself how to code in 2015. My first language was Python. In 2016, I began to move on to modern frontend web design (HTML5, CSS3, ES6). That same year, I was accepted into a tech bootcamp called Coalition for Queens (C4Q), which placed me in their Swft/iOS cohort. C4Q also introduced me to using Github for collaborative projects. I graduated in 2017.

In early 2018, I refocused on C# in preparation for an apprenticeship with Microsoft. I worked there in the spring and early summer.

With the apprenticeship over, I have been studying and practicing web design again.


Past Experience

I worked 6 years as a writer, and have 2 years experience developing mobile and web apps. I am most familiar with Swift, Javascript, and C#.

MediaWiki Projects

https://github.com/srish/MediaWiki-Action-API-Code-Samples/pull/9
Pull request for sample code on the API:Images page. Merged.

https://www.mediawiki.org/wiki/User:Martyav/Sandbox/API:Images
Sandbox for drafting improvements to API:Images page. Approved.
Contents added to live API:Images page (https://www.mediawiki.org/wiki/API:Images)

https://github.com/srish/MediaWiki-Action-API-Code-Samples/pull/17
Pull request for sample code on API:Redirects. Merged.

https://www.mediawiki.org/wiki/User:Martyav/Sandbox/API:Redirects
Sandbox for drafting improvements to API:Redirects page. Approved.

https://www.mediawiki.org/wiki/User:Martyav/Sandbox/API:Lists
Sandbox for drafting improvements to API:Lists page

Other Projects

https://github.com/martyav/sample-programs
The above repo was my first time participating in a large project with strangers, for reasons other than work. I created a code sample for reversing a string in Swift, and also made a thorough article describing Swift's unique language features (https://therenegadecoder.com/code/reverse-a-string-in-swift/). I more recently submitted a code sample for Fizzbuzz in Swift, and am working on a draft for the accompanying article. I think this project is the one most similar to MediaWiki's doc project, even if it is in another language, because it involves writing sample code and explaining it to an audience that may or may not have a lot of background knowledge.

https://github.com/martyav/drawing-pad
A web app for drawing, using HTML5 canvas. My most recent project. It's taught me a lot about the DOM, and how to create a web app, without being dependent on a framework such as jQuery or React. I think any web apps submitted should rely very little on dependencies, to keep them small and evergreen.

https://github.com/martyav/git-CLI-cheat-sheet
Repo describing Git vocabulary and commands in plain language. I created this for students at my bootcamp. I tutored at my bootcamp last year, and many people had trouble understanding Git. I recently updated it with corrections, for the current class.

https://github.com/martyav/nibPractice
Repo with demo teaching an iOS concept. I created this repo while still a student at my bootcamp. A lot of people were having trouble with .nibs (a kind of visual layout file for iOS apps), so I took some screenshots and created a repo with a sample project inside, demonstrating how to successfully use them. I was very careful to describe any pitfalls they might run into while navigating the GUI to wire up their layout.

https://github.com/martyav/swiftBasics
A Swift playground (kind of like a repl) I created for students at my bootcamp, to teach basic programming concepts in Swift.

https://github.com/martyav/ticTacToeHomework
A repo containing a Tic-Tac-Toe demo for students at my bootcamp, with numerous comments describing why things were done a particular way. Intended to teach how to create an iOS app.

https://github.com/martyav/AC3.2-weLearn
A learning management system for iOS. It was my capstone project at my bootcamp. It was the longest collaboration I had participated in up until that point. It taught me a lot about project management and working on a team, refactoring, and updating projects to keep them current.

https://github.com/martyav/algoReview/tree/master/pythonSolutions
This is really the only example I have of working with Python. Python was my intro to programming...but I didn't get active on Github until after I started learning Swift, and by then I was no longer working with Python.

Event Timeline

Martyav created this task.Oct 30 2018, 5:38 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 30 2018, 5:38 AM
Martyav updated the task description. (Show Details)Oct 30 2018, 5:38 AM
Martyav updated the task description. (Show Details)Oct 30 2018, 5:59 AM
Martyav updated the task description. (Show Details)Oct 30 2018, 6:06 AM
Martyav updated the task description. (Show Details)
Martyav renamed this task from Proposal: Improving Top 50 API documentation & creating demo to help users of MediaWiki learn how to use our APIs to Proposal: Outreachy 17 - Improving Top 50 API documentation & creating demo to help users of MediaWiki learn how to use our APIs.Oct 30 2018, 6:24 AM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 6:37 AM

Thanks, @Martyav! Your proposal looks great. A few minor comments:

  • In the summary part, you have mentioned about your current work with microtasks. Instead, here you could include the project summary.
  • Links welcome in the deliverable section where relevant (e.g. link to the demo app on Github in place of my name :)). Same in the Participation section too, provide a link to Github repo.
  • You can remove this question: "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)?". This is applicable only when Outreachy takes place in summer alongside GSoC.
  • Lastly about the project title -- you could consider rephrasing the first part to "Improving ~20 documentation pages and creating a demo app.." as that sounds more reasonable :)
Martyav renamed this task from Proposal: Outreachy 17 - Improving Top 50 API documentation & creating demo to help users of MediaWiki learn how to use our APIs to Proposal: Improving ~20 documentation pages and creating a demo app - Outreachy 17.Oct 30 2018, 6:52 AM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:00 AM
Martyav updated the task description. (Show Details)
Martyav renamed this task from Proposal: Improving ~20 documentation pages and creating a demo app - Outreachy 17 to Proposal: Improving ~20 documentation pages and creating a demo app to help users of MediaWiki learn how to use our APIs - Outreachy 17.Oct 30 2018, 7:06 AM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:13 AM
Martyav updated the task description. (Show Details)Oct 30 2018, 2:19 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 2:24 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 2:45 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 3:12 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 3:19 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 4:39 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 4:42 PM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 4:46 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 4:48 PM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:16 PM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:18 PM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:21 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 7:37 PM
Martyav updated the task description. (Show Details)
Martyav updated the task description. (Show Details)Oct 30 2018, 7:42 PM
Martyav updated the task description. (Show Details)Oct 30 2018, 9:39 PM
Martyav updated the task description. (Show Details)Oct 31 2018, 11:51 PM
Martyav updated the task description. (Show Details)Nov 1 2018, 12:00 AM
Martyav updated the task description. (Show Details)
Martyav closed this task as Resolved.Mar 6 2019, 7:52 PM