Proposal for https://phabricator.wikimedia.org/T115158
Note: There will be frequent updates in this application before 30th March 2017. Suggestions are welcome. Answers to the questions asked in the outreachy template will be updated soon.
Name: Sonali Gupta
IRC handle: mine0901
Email: sonaligpt0@gmail.com
Web Page: http://sonali0901.github.io/
Location: Jaipur, India
Time Zone: UTC+05:30
Typical working hours: 10 AM to 2 AM.
On college days, occupied between 1 PM to 4 PM.
**Abstract**
Citoid service relies heavily on Zotero translation-server which make use of translators to get citation metadata from specific pages. Translators are written for various browser support namely, firefox, chrome, safari, server, internet explorer and bookmarklet. The existing extensive documentation for writing translator in browser plugin is almost 10 years old. The documentation on the wiki is also outdated. For Citoid it is necessary for translators to work in translation-server. This project will focus on preparing documentation on mediawiki.org on how to write a Zotero translator that works in translation-server keeping Citoid in mind and including the current Zotero code updates.
**Extension**
The process of documentation will include the creation of a sample translator. Translation of the above-mentioned documentation in Hindi will be part of the project. Solving bugs in Zotero upstream and writing the requested translators is also in the scope of this project.
**Mentors**: @Mvolz, @czar
**Contribution made for the project**
I have been active on phabricator and I started working and interacting with WMF developers from 23rd February 2017. While working on my first contributions, I communicated with mentors at WMF and Zotero’s developers, asked for help and suggestions. The positive responses helped me decide that I want to be a part of this team and contribute to the best of my potential.
- https://phabricator.wikimedia.org/T95128 - Citation for OpenLibrary returned incorrect author information. The task was to file this bug to Zotero upstream. For solving this microtask I installed Zotero translation-server and tested the bug and reported it upstream.
- https://phabricator.wikimedia.org/T158675 - WM fork of Zotero’s translator repository was behind by several commits and needed an update. This task helped me learn about working with Gerrit and pushing code for MediaWiki.
- https://github.com/zotero/translators/pull/1250 - Deleted an outdated translator.
- https://github.com/zotero/translators/pull/1280 - I created a PR to resolve the bug leading to incorrect citation data (T95128)
- https://github.com/zotero/translators/pull/1282 - Created a translator for a leading English newspaper in India. I explored several concepts while writing it which will be important for the project. I took help of Zotero-translator documentation and existing translators in the same category. The PR is waiting to be merged.
Other deliverables during the internship
- Blog posts on my progress every week.
- Blog posts on my experience with WMF and/or FOSS-related topics at least once every two weeks.
Past Experience in Open Source
I have been a full-time Linux user for 3 years and using open source software all the time. I am an active member of my institute’s FOSS society and Mozilla society. As a member, I have attended and taken up the organisation of various workshops, such as on the Git, Open Source, How to contribute for Mozilla and Womoz. Our team at FOSS organized the conference of KDE in 2016 which was my first open-source conference. I also met WMF contributors at WikiToLearn conference 2017. I started contributing in an open source organization named Zulip during the application period of Outreachy 13 and solved some code based issues, the links to those are -
- https://github.com/zulip/zulip/pull/2188
- https://github.com/zulip/zulip/pull/2208
- https://github.com/zulip/zulip/pull/2079
- https://github.com/zulip/zulip/pull/1873
I did some documentation tasks at Zulip:
- https://github.com/zulip/zulip/pull/1928
- https://github.com/zulip/zulip/pull/1792
- https://github.com/zulip/zulip/pull/1936
I enjoyed working with the community and hence decided to be a Zulip mentor for Google Code-In 2016. The task I handled was the creation of User Documentation for Zulip’s features and improvement of existing User pages. With other the mentors, I helped in designing tasks before and during GCI and I guided students in their introductory tasks and helped them in using git and Github.
**Table of content**
# Brief about Citoid and Zotero translators – This will include synopsis of these software are and their features.
# Relationship between Citoid and Zotero - How Citoid makes use of Zotero will be the focus of this section. What is required in Zotero translators to be compatible with Citoid, the main motivation of the documentation will be explained in this section.
# Installation and setup of required software(procedure explanation through screenshots)
# Explanation of Concepts required to build a translator – General things to know before writing a translator are HTML, Dom, XPath and JavaScript. What purpose they serve and their use will be included.
# Common code blocks in Zotero translators
# For each block, code snippet and the result of the block – There are specific code blocks that are included in almost all the new translators and make it easy for new and old developers to come up with a translator.
# Information of the Zotero Utilities with examples
# Build a sample translator(Screenshots of tools and code snippets) – Following all the above mentioned points, a sample translator will be build at translation-server side.
# Testing a translator - Before a translator is submitted to get live in production, it must be tested by the developer. Use of automated testing by Scaffold.
# Getting a translator live
# Troubleshooting - Common errors faced during installation of tools. General errors thrown by the code. Errors during testing.
# Useful links - Links to courses(HTML, XPath, etc.) , Links to Videos, Links to developer forums.
# See Also
**Elements of the documentation will remain as follows:**
- Sections
- Subsections
- Captions
- Images
- Code snippets
- References
**Timeline(2017)**
30th March - 28th April
- Work with Citoid and Visual Editor. Solve tasks at https://phabricator.wikimedia.org/tag/citoid/ .
- Continue writing new translators.
29th April
- Celebrations
30th April - 29th May
- Community bonding period.
- Search and finalize the sample translator to be used for documentation
- Study the existing translators for blogs, catalog, magazine, newspaper and learn the similarities and differences between them.
- Solve Zotero bugs and write translators. Mark bugs to solve during the internship period.
Week 1(30th May - 5th June)
- Complete section 1 of the documentation, that is, brief about Citoid and Zotero.
- Solve https://github.com/zotero/translators/issues/1206
- Complete section 2.
Week 2(6th June - 12th June)
- Document(section 3) installation of Zotero, Scaffold, Firebug and text editor for JS(code snippets will be for Ubuntu OS user).
- Solve https://github.com/zotero/translators/issues/1020
Week 3(13th June - 19th June)
- Complete section 4(synopsis of concepts needed).
- Cover detectWeb and getSearchResults functions(section 5).
Week 4(20th June - 26th June)
- Cover scrape and doWeb functions(section 5).
- Write subsection about Zotero Utilities.
- https://phabricator.wikimedia.org/T94663
Week 5(27th June - 3rd July)
- Document how to write a translator for the sample site(section 6). This section will have multiple sub-sections holding code snippets and the return values of those codes. This section can be finished smoothly making use of already provided documentation in the previous sections.
Week 6(4th July - 10th July) + Week 7(11th July - 17th July)
- Section 7,8,9,10,11
The documentation will be shared to be reviewed by developers at Zotero and WMF and their ideas/suggestions will be incorporated. Once the content is developed, Hindi translation will be easy. The crucial(and time taking) part for Hindi translation is typing in Hindi and researching words that are commonly used in other pages on MediaWiki.
Week 8(18th July - 24th July)
- Complete section 1,2,3
Week 9(25th July - 31st July)
- Complete section 4,5
Week 10(1st August - 7th August)
- Complete section 6
- https://phabricator.wikimedia.org/T160273
Week 11(8th August - 14th August)
- Complete section 7
Week 12(15th August - 21st August)
- Document section 8,9,10,11
- Share the documentation for review + improve it.
Week 13(22nd August - 30th August)
- Give final touch to documentations and get approval from the mentor for English and Hindi.
- A blog post for my complete journey.
30th August and later
- Celebrations
- Start code-based contributions in WMF. Explore Citoid and other projects on WMF to contribute to.
- Be an active member of the community.
- Participate in future programs as a volunteer and a mentor.
Every week. I will post blogs about my progress and get my work reviewed by mentors. This will help cleaning each section before moving to the next in the following weeks.