Page MenuHomePhabricator

Review and improve the documentation for Google Code-In 2016
Closed, ResolvedPublic

Description

Event Timeline

I took a first look at the wiki page for Google Code-In https://www.mediawiki.org/wiki/Google_Code-in_2016 and here are some initial thoughts/ ideas that I am considering to apply:

  • Make separate pages for students and mentors.
  • Make instructions a bit more concise, categorized and in a step-by-step format.
  • Too many links on the GCI page seems distracting. If some of the important topics such as code review, amending a change, etc. are already explained in-depth in the Gerrit tutorial, then do not link them from the main page but highlight them in a separate bullet point.
  • Make titles a bit more self-explanatory e.g. change 'General Recommendations' to something being like "How to get started?" or "How to make your first contribution?".
  • “Feedback, Questions, and Support” and “Communicate that you work on a bug” section seems to contain some duplicate information. So either re-organize or combine the two sections such that the new one contains information about how or when you communicate.
  • Should we consider adding mentors email ids in the list of mentor's section so that it's easier for students to reach out?
  • 'Common Instructions for tasks' section is a bit confusing to understand in one go whether it belongs more to students, mentors or both. Organize it better.
  • Improve the design of the page, add GCI logos, make it a bit fancier, to catch kids attention :), etc.?

@Aklapper Looking forward to your thoughts before I start making any changes and also want to know if this should wait until we get accepted?

I agree with point 1, we should move the bulk of the mentor section to
another page and then link to it.

I would keep most of the student directed stuff on the main page. Students
might have trouble finding it otherwise.

The special directions bit I would also move to a new page; it's pretty
outdated and some of the projects aren't even featured?

I agree with point 1, we should move the bulk of the mentor section to
another page and then link to it.

Sounds good!

I would keep most of the student directed stuff on the main page. Students
might have trouble finding it otherwise.

For this, I was thinking of adding two different sections on the left and the right of the main page that says something like: 'participate as a student', OR 'mentor a task'. And from there we take users to the corresponding student and mentor page for further instructions.

The special directions bit I would also move to a new page; it's pretty
outdated and some of the projects aren't even featured?

Thanks a lot to both of you providing a fresh view!
Also CC'ing @Nemo_bis and @Petrb for potential input (if they have time&interest) as they have org admin expertise from previous years.

I generally agree with most things, adding some additional thoughts. Now please disagree with me! :P

https://www.mediawiki.org/wiki/Google_Code-in_2016

  • Make separate pages for students and mentors.

Very good point. I'd favor making the main page (mw:Google_Code-in_2016) for students, and have one line at the top for mentors linking to a subpage. So I'd move mentor info https://www.mediawiki.org/wiki/Google_Code-in_2016/Mentors or such. I wondered about link breakage but the #Mentor's_corner anchor has only been mentioned in a single email so far hence should be 'early' enough. Wondering if we could leave the "Mentor's corner" section with content being a single line linking to the new location until the contest starts and then remove it?

  • Make instructions a bit more concise, categorized and in a step-by-step format.

Generally yes! I prefer "How can I do X?" style and step-by-step checklists.

  • Too many links on the GCI page seems distracting. If some of the important topics such as code review, amending a change, etc. are already explained in-depth in the Gerrit tutorial, then do not link them from the main page but highlight them in a separate bullet point.

Generally agreeing (if I get you right). We do suffer from throwing dozens of links onto people, you'll experience the same disease on other pages targeting new contributors.

  • Make titles a bit more self-explanatory e.g. change 'General Recommendations' to something being like "How to get started?" or "How to make your first contribution?".

Yes! If we rename Instructions_for_GCI_students though we need to update the link in the "What is shown at the bottom of every task in the GCI site" boiler text setting on the GCI site - easy to do, just a reminder.

  • “Feedback, Questions, and Support” and “Communicate that you work on a bug” section seems to contain some duplicate information. So either re-organize or combine the two sections such that the new one contains information about how or when you communicate.

Yes. These sections are an exact copy from mw:How_to_become_a_MediaWiki_hacker so edits should happen on both pages. I would love to use Labeled section transclusion (LST) to avoid such duplication of content (copied content getting out of sync), but I failed spectacularly last year as the Translate extension and LST do not seem to be friends. Hence the copying. :(

  • Should we consider adding mentors email ids in the list of mentor's section so that it's easier for students to reach out?

I'm torn on this. I don't want single points of failures and (in theory) I want students to interact with our communities instead of single persons. Hence mailing lists and IRC where other people are also around to help (as I cannot read your private email conversations). If that idea makes sense... you decide. :)

  • 'Common Instructions for tasks' section is a bit confusing to understand in one go whether it belongs more to students, mentors or both. Organize it better.

In theory: Mentors to write it, students to read it. In theory. In a perfect world these sections are part of the task descriptions on the GCI site (and maybe in our corresponding Phab tasks) but last year we ran into a 1500 letters limit for task descriptions on the GCI site. But yeah this should likely be in the Mentors section / on the Mentors page, as Mentors are supposed to add such project-specific boilerplate text to task descriptions.

  • Improve the design of the page, add GCI logos, make it a bit fancier, to catch kids attention :), etc.?

Yes, like GCI logo and Wikimedia logo. Though need to check license of GCI logo and what can be hosted on mediawiki.org. Wondering if we can also find an image of last year's Grand Prize winners visiting the Google headquarters. We also link to blog posts written by students after GCI 2015 had ended at the bottom on the 2015 page - might be an interesting motivational read to link to.

@Aklapper Looking forward to your thoughts before I start making any changes and also want to know if this should wait until we get accepted?

Do it now! :D

For this, I was thinking of adding two different sections on the left and the right of the main page that says something like: 'participate as a student', OR 'mentor a task'.

The page currently only targets mentors and students so I think not much would be left if we removed info for both groups to subpages. I'd keep the student info on the page - one click less.

@Aklapper thank you for your wonderful feedback, time for action is now :)

  • Improve the design of the page, add GCI logos, make it a bit fancier, to catch kids attention :), etc.?

I've added the logo.
I also looked at Google's GCI blog posts and one includes a photo of GCI 2015 Grand Prize winners but I do not know its license (TODO).

For this, I was thinking of adding two different sections on the left and the right of the main page that says something like: 'participate as a student', OR 'mentor a task'.

I've added two 'buttons' on top for the main two actions why you'd visit the wiki page. (Thanks for the idea!)

  • Make separate pages for students and mentors.

I've created a separate subpage for mentors, and moved content but kept a link in the Mentors section (section to be removed when the contest starts).

That's what I could do for now; leaving other items mentioned in this task to @srishakatux.

  • Improve the design of the page, add GCI logos, make it a bit fancier, to catch kids attention :), etc.?

I've added the logo.
I also looked at Google's GCI blog posts and one includes a photo of GCI 2015 Grand Prize winners but I do not know its license (TODO).

I think @Florian has some GCI photos I'd imagine he'd be willing to license for use on the wiki. :)

I think @Florian has some GCI photos I'd imagine he'd be willing to license for use on the wiki. :)

All images I took, I already uploaded to Commons, so feel free to use them as licensed :D
https://commons.wikimedia.org/wiki/Category:Google_Code-in_2015

I'll ask Stephanie, if she (or anyone else who holds the copyright) could upload it to commons, or if we're allowed to do so :)

@Florian Thank you for sharing the link! @Aklapper Here are a few changes that I have made to the main wiki page, and tried to make the following changes:

  • Made instructions a bit more concise, categorized and sequential
  • Removed duplicate information which is also available on our other development related tutorials
  • Removed too many links
  • Changed titles of sub-headings
  • Re-organized the content of two previous communication-related sections
  • Added a picture (though it's from 2014). As we do not have any with a better resolution from 2015, I've emailed Stephanie asking if we could use a couple of photos from the ones uploaded by Google (thanks for the tip @Florian!).

Any feedback (+ve, -ve) would be helpfuI :) I especially need some inputs on the "Choose tasks and read the related documentation" section for tasks that are not coding related. I am not sure the last bullet point is apt, or if we could add more?

@srishakatux Hehe :P I already asked Stephanie, and actually she's reaching out to the Googler who took the images from 2015, if he want to share the images with a free license with us or not :P