As you may have noticed, GNOME was recently accepted as a participating organization in the Season of Docs 2020 program (thanks Kristi Progri, Shaun McCance, and Emmanuele Bassi for your help with this).
While we are eagerly awaiting potential participants to apply for the program and start contributing as documentation writers to GNOME user and developer documentation projects, I also wanted to summarize recent updates from the GNOME documentation infrastructure area.
Back in January this year when conferences were not solely virtual, Shaun McCance, David King and yours truly managed to meet right before FOSDEM 2020 in Brussels, Belgium for two days of working on a next-gen site generator for GNOME user documentation.
As largely unmaintained library-web running behind help.gnome.org remains one of the biggest pain points in the GNOME project, we have a long-term plan to replace it with Pintail. This generator written by Shaun builds Ducktype or Mallard documentation directly from Git repos, surpassing the need to handle Autotools or Meson or any other build system in a tarball, as opposed to library-web, which, for historical reasons, depends on released tarballs generated with Autotools only, with no support for Meson.
With the help from the awesome GNOME Infrastructure team, we managed to get a test instance up and running at help-web.openshift.gnome.org for everybody to review. The sources are hosted at gitlab.gnome.org/Infrastructure/help.gnome.org. Please keep in mind that this all is very much a work in progress.
We summarized some of the top priority issues to resolve as a follows:
- Finalize site design to be on par with what users can found on help.gnome.org currently.
- Add translation support for the site, so users can access localized content.
- Figure out the right GNOME stable branching scheme support to be used by the site.
Initially, we plan to make latest stable and unstable (master) versions for each GNOME module available. We want to have branching and linking configuration automated, without the need to manually reconfigure documentation modules for every new branch or release, just like in library-web. However, adding that support to Pintail requires some non-trivial code to be written and we had David looking into that particular area.
With the limited amount of time we had during the pre-FOSDEM days, we still managed to make a considerable progress towards having a documentation site replacement ready for deployment. But as it is common with volunteer-based projects, the pace of work often slows down once the intense hacking session is over.
I think we all realize that this area really needs more help from others in the community, be it Infrastructure, web design, localization, or simply community members submitting feedback. Please check out the help-web project on GNOME GitLab and leave comments, or, even better, submit merge requests.
Thank you Shaun and David for your time and help!