The GNOME Documentation Team last met for a documentation hackfest back in 2015, following the Open Help Conference hosted by Shaun. After my not so successful attempt at organizing a meetup for both upstream and downstream (Ubuntu) teams to hack on GNOME docs some time in 2017, we finally succeeded in meeting in the upstream format for the West Coast Hackfest from 18th through 21st July 2019. That event organization was kicked off by the folks from the GNOME Engagement team and Foundation staff and gave us an opportunity to hold a co-located event with Documentation, Engagement and the GTK team sharing the venue and allowing for more focused cross-team collaboration.
After the 3-year long hiatus in having hackfests, the docs team’s primary goal was to get back on track with triaging outstanding documentation bugs for the GNOME documentation core set (GNOME Help and the System Administration Guide). We did not only work on the triaged bugs but made an effort to fix as many parts of the user help as possible, reviewing the content mostly written several years ago against the new features that in the meantime landed in GNOME.
The group that gathered at the hackfest, David, Michael and Jim, are all veteran GNOME writers responsible for authoring a substantial part of the current documentation set, so we didn’t have to spend additional time getting up to speed with the writing process. After the initial doc bug triaging in the gnome-user-docs and gnome-getting-started-docs projects on GitLab, we were off to writing.
In previous sprints, we sometimes struggled with getting an easy-to-use early access to development versions of GNOME that would allow us to quickly focus on the writing. This year we were much better prepared with the availability of Fedora Silverblue. Switching to a rawhide branch from the running system to get the latest bits turned out to be easy, whether we ran the system on bare metal or in a VM, though we also faced some problems often found in development versions, for example, the Wi-Fi adapter on one of the laptops wouldn’t work.
We had a look at making our docs module continuous integration much more robust. We now fail on unsuccessful merge of translated strings when building translations by switching itstool to strict mode:
./autogen.sh ITSTOOL="/usr/bin/itstool --strict"
This change should make the common problems with missing XML tags in translations more visible.
We now also call yelp-check tests from gitlab-ci.yml as those are not run during make check or distcheck. Last but not least, we run a bunch of xmllint –schematron tests that check for problems such as a missing legal notice include, missing <desc> element, etc. Turned out those tests were written many years ago by Shaun but that somehow slipped through the cracks for the team and the tests would not really be run.
As this hackfest was a co-located event, I also had a chance to sit down with the Engagement team too to go through some of the wiki pages for contributors to both GNOME documentation and localization and identify outdated information or areas for improvement.
Most of the core hackfest days were spent on updating different areas of GNOME Help topics, reviewing the content against recent (and not so recent) changes in the UI. However, we also touched on the subject of the future of the GNOME documentation site and using the Pintail site builder we want to deploy as a replacement for the old library-web, which over the years became mostly unmaintained, now missing support for building Mallard documentation from Meson-based tarballs, for example.
With the GNOME initiative from last year attempting to bring up a new site for developer documentation, the project requirements for the developer docs and user and sysadmin docs seem to be slightly different. The developer site hosts, for the larger part, narrative content such as tutorials as well as API reference. It might make sense to treat these two areas separately and and come up with a different approach to each of these, not necessarily using the same build process as it is now.
For the user and sysadmin documentation site, on the other hand, our primary goal is to use a solution that let us keep using the current Mallard-based documentation format and toolchain. Pintail is a tool Shaun wrote for generating the projectmallard.org site that documents the Mallard format itself. It adds all the navigation and translation logic on top of the Mallard-based content, but the most substantial difference from the library-web is that the build process is not based on released tarballs containing documentation, but it simply builds the content from a live git version, working with the git repos and branches directly. That gets the whole build process closer to the popular idea of treating docs as a code and having a continuously updated preview of the docs available on the docs site.
We originally planned to preview a local instance of the Pintail-based help.gnome.org site Shaun prepared a while ago, but then we ran into some build issues that need to be tackled later when we have Shaun around.
Having said that, reworking our docs site remains the very top priority for us, but I’d like our team consider working on other longer-term goals, as well, such as switching to the Ducktype lightweight documentation format, which would get the writing experience much closer to what other popular open source documentation projects out there started to use (Markdown, AsciiDoc, reStructuredText) instead of the once much more popular XML-based formats.
In addition to that, there are more project tasks that we did not have time to focus on this time, with one of them being redesigning the landing page and navigation experience for GNOME Help. That one will need to be given more thought and feedback on how we want to structure the topmost topics and what we want to show the user upon opening Help. A part of that work should be finishing the overhaul of getting started topics and replacing most of the getting started videos with easier-to-maintain SVG graphics.
At the hackfest venue, which turned out to be a really nice co-working space south of Portland downtown, David shot a timelapse video with the team busy at hacking, that I wanted to link from here, too.
I’d like to thank the GNOME Foundation for funding my travel, the Foundation staff for helping organize the event, and Red Hat for sponsoring my time at the hackfest.
