May 3, 2020

GNOME Season of Docs 2020

GNOME is applying to be a participating organization in the Google Season of Docs 2020

About GNOME

GNOME is a worlwide community that creates a desktop environment, applications, and the underlying technology. GNOME has a long history of design-oriented development, and of working on all parts of the stack to create a good user experience. The GNOME documentation team has worked on both user and developer documentation for over two decades, and was one of the pioneers in creating modular, topic-oriented help.

The GNOME community is loosely organized, with different people teams working on different parts of the project. We strongly value all kinds of contributions, including design, documentation, translations, and outreach. GNOME is more than code.

GNOME has a long history of working with mentoring and outreach programs, including the GNOME Newcomers initiative, Google Summer of Code, and Outreachy (which was incubated in GNOME as the Outreach Program for Women).

Please read our code of conduct.

Get in touch

Mentors for the Season of Docs are:

  • Petr Kovar <pmkovar AT gnome DOT org>
  • Shaun McCance <shaunm AT gnome DOT org>
  • Emmanuele Bassi <ebassi AT gmail DOT com> (developer docs)

But you are encouraged to talk to the entire team and the wider community:

Information for technical writers

Before you begin, we encourage you to reach out to the team and introduce yourself. We strive to be a welcoming community, but we also value seeing initiative from contributors. You will work with a number of technologies and systems. Some might be familiar to you. Some might not. If you would like to start learning on your own first, that’s great, but we are prepared to teach you what you need to know. Here’s a (probably incomplete) list of what you might learn, depending on project:

  • Mallard, a modular, topic-oriented documentation language and framework.
  • The git version control system. git can be intimidating, but it is used by most open source projects these days, and it enables some powerful workflows.
  • The merge request workflow on GitLab, similar to the pull request workflow on GitHub.

In addition to your project, we would appreciate if you keep a log of things you find difficult when learning to contribute. This will help us improve the onboarding process in the future.

Project ideas

Below are three ideas for projects.

1. GTK documentation

Summary: Review and update the structure and content of the GTK API reference.

Description: The GTK API reference is made of two parts: one is the description of each function and type in the API; the other is more “narrative”, and contains a general description of each class; overview of complex, interdependent classes (e.g. GtkTreeView, GtkTreeModel, GtkCellArea; or GtkTextView and GtkTextBuffer); a short tutorial on how to write an application using GTK. This second part is the one in need of review and update. The tone and structure of the documentation should be consolidated, and made more appropriate for newcomers to the library.

2. GObject tutorial consolidation

Summary: Review and update the content of the GObject tutorial and overview

Description: The GLib object type system documentation contains an overview of the type system and of the base object class, with topics ranging from the lifetime of an object instance, to how to install properties; from interfaces to best practices on how to write object types; and a tutorial, which covers similar topics in a more narrative way. Ideally, we should only have a tutorial covering all topics, and have specialised, in-depth documentation for the more complex aspects of the API. The base concepts section should be merged with the tutorial section by having the former section use examples and a more narrative voice from the latter.

3. Content audit and gap analysis for gnome-help

Review all of topics in gnome-help (part of the gnome-user-docs documentation module). Identify information that is out of date or misleading. Review recent changes to GNOME to find areas where gnome-help is missing information. After the audit and gap analysis, there should be time for significant writing, but we don’t expect the technical writer to close all issues identified.

Revisit which information is presented to readers of gnome-help, and how it is presented. Identify what information people need the most and formulate a content strategy.

4. Update app help

Review and update the help for a number of GNOME applications as tracked in https://wiki.gnome.org/DocumentationProject/Tasks/ApplicationHelp.

SeasonofDocs_Logo_MainGrey_300ppi.png