Through the maze of newcomer developer documentation

by
Translate this post

This post is a discovery report written by David Wood and slightly edited for publication. It’s part of a series of candid essays written by Google Code-in students, outlining their first steps as members of the Wikimedia technical community. You can write your own.

This discovery essay touches on my general thoughts as I initially started to browse and look into developing for MediaWiki.
I’ve split it into three sections: Setting up, where I cover my experiences while working with pywikibot for a previous Google Code-In task; First Impressions, where I describe my thoughts as I browse the documentation geared towards newcomers; and Developer Hub, where I describe my thoughts as I venture into the actual development articles.

Setting up

Before looking to develop for MediaWiki, I had previously completed a task relating to pywikibot. I found that the mentors were very helpful and available for advice.
However, I did find issue with setting up the development environment for work on pywikibot. It seemed very complex, and at first I did not fully understand what I was required to do. For someone who hasn’t worked on large-scale projects before, such as MediaWiki, I was confused as to why it was required to have so many accounts and things set up beforehand, such as a Gerrit account.
Although I now understand, I feel that a guide explaining to newcomers, not necessarily new to collaboration with git, but to using less known tools such as Gerrit, why they are necessary, would be helpful. And although I understand that in some cases not much can be simplified as setup is complicated, perhaps a more in-depth guide would help as well (keep in mind, this is referring to the guide for installing pywikibot, and the guide for MediaWiki in general may be better).

First impressions: a guided tour for newcomers

Coming from only basic experience with a small project within MediaWiki, I was pleasantly surprised with the quality of the information and simplicity of it from the How to become a MediaWiki hacker page. There was a lot of information, for example, instead of simply telling the reader that they required knowledge in PHP, MySQL and JavaScript, the guide went on to link them to where they could gain such knowledge.
From there, I went to read A brief history and summary of MediaWiki. This was especially interesting as not only was it a engrossing read, it also helped the user understand the principles under which MediaWiki is developed, such as the fine line between performance and functionality. Such information helps a new user, such as myself, understand the goals behind MediaWiki and the mindset in which I should be working.
Another pleasant surprise was that even the more technical articles, such as Security for Developers, were written in plain English, without a lot of technical language. And even where it got technical, it was explained well. Guides that have a lot of importance, such as this one relating to Security, benefit even more from being simple for newcomers than most, as it’s more likely then that a newcomer would understand and implement what they’ve learnt.
Another note I made was that all the links that would be relevant to newcomers, such as Coding Conventions, were all easily found.

Developer Hub: What next?

My next stop was the Developer Hub, where I found that I wasn’t sure how exactly to proceed. There, unlike the last article, didn’t seem to be a clear path to follow when traversing the article, most likely due to this article not being geared directly towards newcomers to MediaWiki.
This is where I experienced most issue; from here there was no more crutch helping me along. I somewhat expected, as I had seen on other projects, there to be a simple guide for what to do next for newcomers and, unless I couldn’t see it, there wasn’t one. I was left unsure as to what to do next; Should I just start browsing code? Look at feature requests? Or for bugs? I think this is where some guidance would be helpful for newcomers; getting to this point was well documented, but after you’ve set everything up, you’re left wondering what next. Some sort of list of easy bugs, or projects for newcomers to contribute to, would give some guidance as to what type of contributions they should be looking to make next.
I also noted that some information linked from the developer hub, such as an archived roadmap, was out-of-date or marked as only available for historical purposes. While I understand the reasoning behind this, it’s still confusing as these links are still prominent on the page.

In conclusion

While I didn’t install MediaWiki personally, my experiences toward the complexity of setting up things, as detailed in the first part, where from a pywikipediabot perspective, as I come from a python background rather than a PHP background. I would consider however contributing to MediaWiki in the future, if I ever take time to learn PHP, as it not only seems a enjoyable experience, but I appreciate the ideologies behind MediaWiki, to support a community that creates and curates freely reusable knowledge on an open platform.
David Wood
2013 Google Code-in student

Read in this series:

Archive notice: This is an archived post from blog.wikimedia.org, which operated under different editorial and content guidelines than Diff.

Can you help us translate this article?

In order for this article to reach as many people as possible we would like your help. Can you translate this article to get the message out?