The GNOME Newcomers initiative

At GUADEC 2016 in Karlsruhe, Germany, Bastien Ilsø and Carlos Soriano reported on the revamped Newcomers section of the GNOME web site. The section is intended to draw in new users and developers and help them find their way around the project as well as to help them get the necessary development environment set up to begin contributing code.

The predecessor of the new outreach site was the "GNOME Love" section of the project's wiki (an Internet Archive capture of the page is available here). Conversations about replacing it began in 2014, Soriano said, although the work did not start in earnest until mid-2015. The name of the page was an obvious problem, he said: at best it gave no hint as to the content of the section; at worst it suggested the wrong thing entirely, like a "GNOME appreciation" project. But the team identified many other issues. The GNOME Love section assumed a lot of knowledge on the reader's part, including experience with Git, Bugzilla, patching tools, packaging, dependency management, and the GNOME build tool JHBuild.

Furthermore, the content was insufficient. JHBuild, he said, is a generic utility (even though it is optimized for building GNOME), so using it requires first setting up the correct build configuration. And the instructions on GNOME Love relied mainly on linking to existing tutorial and reference material from elsewhere, which made it hard to navigate—and potentially confusing, when those external resources got out-of-date. He noted that when talking to users asking for help, the first question a member of the GNOME team had to ask was "which guides have you been reading?" followed by "how far did you get in them?" Finally, the documentation tried to do too much in some regards, such as providing setup instructions for every major Linux distribution.

The rebranding work, Ilsø said, started by updating the name and visual iconography of the site. It then did away with the external links, replacing them with a four-step "how to get started" plan. The steps listed are "choose a project," "build the project," "find and solve a task," and "submit the patch." Each is addressed in its own page, using new documentation written for the purpose.

The "choose a project" page was deemed to be of particular importance, since it is the first step. The page highlights seven GNOME programs (chosen from a rotating list), with each project's section listing specific information about the code, one or more new-contributor mentors from the team, and the project's IRC channel. Each project also has a "Contribute" page in its own section of the GNOME wiki; Ilsø said that templates had been provided to ensure that every project could provide a standard set of information.

The "build the project" section was streamlined, focusing on just two distributions: the most recent releases each of Fedora and Ubuntu. The "find and solve a task" page introduces the development tools and issue-tracking, while the "submit the patch" page explains explains a basic Git-based workflow.

In general, Ilsø and Soriano said, the revamped guide has been well received, but it still needs further work. Partly this will involve updating the instructions to support the Builder IDE and the new Flatpak sandboxed-application package format. Working on a Flatpak will be far simpler and require less setup for new users. The Newcomers page also still needs to be linked in from several other sections of the GNOME web site, in particular from other "entry points" like the various engagement, documentation, and translation pages. It could also be expanded to better explain how the different components of GNOME fit together.

But there will also need to be changes made to the developer documentation hosted at developer.gnome.org, which exists outside of the Newcomers section. Like the old GNOME Love section, that site contains scores of documentation pages that vary considerably in how up-to-date they are. Ilsø noted that he knows how old the "introduction to GTK+" material is, because he rewrote it himself more than a year and a half ago, and it has not changed since. But the team has a plan in place; it met at FOSDEM 2016 and held a hackfest to scope out the necessary improvements to the documentation. Allan Day has also helped by developing mock-ups of how to reorganize the material.

Finally, the speakers reminded the audience that even the rewritten material still assumes that the newcomer involved has experience with GNOME and with desktop Linux in general. While likely to be true, it would be better to provide newcomer information that was accessible to a broader audience. But developing that material might be best done in conjunction with downstream distributions and upstream software projects, they added, given the breadth of the information it could encompass.

Audience members asked what individual project teams should do to better coordinate with the Newcomers section. Ilsø and Soriano replied that each project listed on the "find a project" page had to have an official mentor and ensure that there are also bugs in the official bug tracker that are tagged as being for newcomers.

Attracting new developers always takes work. Large-scale development efforts like GNOME can have an even more difficult task in helping to get potential new contributors oriented, given the size and complexity of the project. While work remains to be done, the revitalized Newcomers section is a marked improvement over the old GNOME Love site.

[The author would like to thank the GNOME Foundation for travel assistance to attend GUADEC 2016.]