Page MenuHomePhabricator

Sort out concept for overview/entrance pages targeting our developer audience
Closed, ResolvedPublic


This task belonged to a goal committed for Developer-Advocacy (Oct-Dec 2017).

Completion of a first pass to our documentation for new developers in, structuring pages, updating and cleaning information. Test the refreshed docs with Outreachy Round 15 and Google Code-in 2017 participants, and review accordingly.

We have a good bunch of pages and resources [partially] targetting [new] developers:

Problems (not a complete list, feel free to add):

  • Different established community members send potential new contributors to different pages due to unclear scope differentiation.
  • Pages are text deserts with gazillions of links, overwhelming anyone who just wants to get stuff done.
  • Some concepts work better/worse than others (e.g. having mentors via Featured Projects vs 'You're pretty much on your own' via Annoying Little Bugs) and we don't communicate these different concepts to potential new contributors to allow judging themselves ("Do I need more handholding or do I prefer to find my way on my own?")

Allow potential new contributors to succeed more often by

  • having pages which offer a clear contribution path forward and guide the new contributor
  • having pages with a clearer, communicated scope
  • communicating that pages which are link collections are not "guides" or "tutorials" or such (but maybe "resource hubs" or whatever)
  • potentially reducing the number of pages targeting similar audiences
  • making people feel responsible to garden some pages, also against well-meant attempts to add more and more content / links

Related Objects


Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

All this looks like a solid plan! :) Adding a few thoughts below, warning.. some of the stuff might be beyond the scope of this task but a related discussion:


  • How to contribute page from navigation & design perspective -- this page seems to have duplicate links in the top navigation & in the content body (e.g. tech forum, tech news, etc.) Also “Wikimedia Technology” & “Wikimedia Audiences” sounds like buzz words. They could perhaps be merged with the product development page. This page also has too many categories that could be reduced.

Totally agree. As an interested new contributor I have no idea what all these items are, if they are relevant for me, if I should click them to get more confused.

  • IMO Newcomer portal only be a step-by-step guide to help a new developer finish a task. And, all the other stuff like communication, outreach programs, etc. can be linked from How to Contribute page itself. We also have an opportunity here to think about offering a newwww newcomer channel and mailing list which we make clearly accessible from the portal. Visualizing... something like this >

Screen Shot 2017-07-10 at 11.03.30 PM.png (1×2 px, 358 KB)

Yes. Trying to list "must haves", not "can haves".
(Example: "It is always better to follow and share the news of MediaWiki across your social network." makes me scream "No it is not").

However where to list "other stuff" (additional resources) depends on who we target on which page.
Random made up example: Not much sense to list for example "wikitech-l@" on "How to contribute" if you're into translating the UI?

That screenshot looks neat. Not like the rest of the grey 1990es.

  • Introduction to Wikimedia tech -- happy to help prepare content for this, work with comms and develop a video with voiceover, subtitles, etc. as I shared on our cep list once. Something like this.
  • Page names IMO:
    • “Newcomers” sounds more friendly than “New Developers.”

True, however good terms are already overloaded (think "project"). I don't want to confuse and mislead. I can be a newcomer in many different ways. This page explicitly targets new developers. Newcomers (in whatever areas) should go to How_to_contribute.

  • “Contribute” sounds better than “How to contribute”. Same goes for our other pages that start with "How to..".
  • I killed "Starter kit" (see its old version here) and redirected it to "How to contribute".
    • The intro was useful hence I copied it into [[How to contribute]].
    • I copied recommending to register an account on and info how to edit, discussing, and your user page into [[How to contribute]].
    • "Communication" listed both passive following ("social media") and actual conversations (IRC, mailing lists). Shortened version copied to [[How to contribute]].
    • Some parts in the "Hacking" section were useful, hence copied into into [[How to contribute]].
    • I don't see why it listed wikitech-announce@. That's for admins/high-level mostly? I don't follow that list, why should someone else?! Why not Tech News instead?
    • The page was linked at the top of [[How to contribute]]. Just to link back to where you came from for "Check the areas to contribute". That did not make sense.
    • Explaining Phabricator and Gerrit was irrelevant at this stage. I only need to know that if I decide to start hacking on projects and on projects which actually use them, hence nothing for a generic "Starter Kit". That stuff is covered by [[How to become a MediaWiki hacker]] already which is linked from [[How to contribute]].
    • QA and API and Translation were already listed on [[How to contribute]], needlessly duplicating content and stuff I'm supposed to read.
    • Again, running MediaWiki and Vagrant is only relevant if I decide to start hacking on projects which require MediaWiki itself, hence nothing for a generic "Starter Kit". That stuff is covered by [[How to become a MediaWiki hacker]] already which is linked from [[How to contribute]].
    • Learning how to use the MediaWiki software is only relevant here if I decide to start hacking on projects which require MediaWiki itself. That's covered by [[How to become a MediaWiki hacker]] already which is linked from [[How to contribute]].

Note to myself: The replies under "What did you find most confusing about the existing Wikimedia technical documentation?" on mw:Hackathon 2017's Questions for newcomers probably also fuel T156301 and this task. For example "if I look for an short answer - I get also a lot background infos on the actual topic".

...and Rachel just pointed to . Which I had not seen before. Which looks great, great, great. (Apart from the fact that a few projects do not use Wikimedia infrastructure like Gerrit/Phab etc, but generally it's beautifully clean).

Note to myself: Once videos are available, go through learnings from GUADEC 2017 conference about GNOME's Newcomers page from session - page design, IRC bridging, etc
Slides at

Edit: Video is at

Added information about the technical advice meeting on the New Developers page.

Technical Advice IRC Meeting|'''Join us for the weekly technical advice meetings every Wednesday from 3 to 4 pm UTC on #wikimedia-tech''

#wikimedia-tech and not #wikimedia-devrel?

So... I believe that understanding and defining which pages should be Tutorials vs How-Tos vs References is the key.
I urge anybody to read (pretty much the talk I attended at Write The Docs conference).

This task will expand to October.

....and dropping a quote from an email by bd808 here, so it's not forgotten in my inbox:

[[How_to_become_a_MediaWiki_hacker]] [...] I was really struck by a few things:

  • Its about more than MediaWiki, but you need to read in pretty far to figure that out.
  • The TOC is a big scary wall of keywords that are probably foreign to most actual newcomers to the community.
  • Making LDAP accounts, Gerrit, and MediaWiki-Vagrant the jumping in point might not really be the best introduction to our larger world.
  • Code of Conduct is only mentioned in the "See also" section.

and Quiddity mentioned as an overview

Liked the approach of "Mentored" and "PatchWelcome" bugs that I discovered here: We could also consider experimenting with this model.

Finally digitalized the drawing on my table that describes the current situation.
Straight arrows (⟶): Page directly advertises another page.
Dashed arrows (⤏): Pages mentioned under "Additional resources" or "if you are looking for XYZ instead / if your skills are XYZ instead".
One could add a billion more pages I guess (see list in task description).

T169599-201901.png (385×464 px, 29 KB)

Didn't check WRC (hence no arrows) as I get lost and see lots of non-dev stuff under "For Developers" (for example, "Frequently asked questions – Participation: Learn more about participating on the Wikimedia projects." goes to which is entirely about content which feels out of scope if I am into code).

Aklapper raised the priority of this task from Medium to Needs Triage.
srishakatux claimed this task.

(this task served its purpose! closing it now <3)

srishakatux awarded a token.