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.
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.
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.
Back from GUADEC, held in the beautiful Andalusian city of Almería, Spain, from 6th July through 11th July, 2018, I wanted to share a few notes wrt documentation and localization activities at the conference and during the traditional post-conference hacking days.
Mike Hill and Rudolfs Mazurs already blogged about their reflections of GUADEC. I’d add that we had some i18n and L10n-related talks in the schedule (machine translations, input methods), which was a nice improvement in terms of representation from previous years.
The space available for the Birds of a Feather sessions this year was rather limited, so we could only secure an afternoon slot (thanks Kat!) for our docs+translators meetup. We were joined for a while by a group of local documentation writers creating Spanish manuals for the local market. After that, we focused on two main areas.
One was related to the recent migration of GNOME projects to GitLab and involved looking into usability of our wiki docs for contributors and, specifically, newcomers. We found quite a few outdated references to git.gnome.org, Bugzilla and the like, with the biggest issue, however, being the suboptimal overall structure of the contributor guides on the wiki. We also looked into how to improve submitting user feedback and switching languages for the users of help.gnome.org (and yelp).
The other area discussed was making our CI checks for GNOME documentation modules much more robust, with the idea of using the GitLab CI integration to its full potential with tests verifying translations and more.
You can find all notes from the meetup in our Etherpad.
There was also some continued discussion on reworking the GNOME developer center, but I couldn’t take part in its final installment on Wednesday, as I was already flying out.
I’d like to thank the GNOME Foundation for their continued support in funding my travel.
With GUADEC 2017 and the unconference days over, I wanted to share a few conference and post-conference notes with a broader audience.
First of all, as others have reported, at this year’s GUADEC, it was great to see an actual increase in numbers of attendees compared to previous years. This shows us that 20 years later, the community as a whole is still healthy and doing well.
At the conference venue.
While the Manchester weather was quite challenging, the conference was well-organized and I believe we all had a lot of fun both at the conference venue and at social events, especially at the awesome GNOME 20th Birthday Party. Kudos to all who made this happen!
At the GNOME 20th Birthday Party.
As I reported at the GNOME Foundation AGM, the docs team has been slightly more quiet recently than in the past and we would like to reverse this trend going forward.
At the GNOME 20th Birthday Party.
We held a shared docs and translation session for newcomers and regulars alike on the first two days of the post-GUADEC unconference. I was happy to see new faces showing up as well as having a chance to work a bit with long-time contributors. Special thanks goes to Kat for managing the docs-feedback mailing list queue, and Andre for a much needed docs bug triage.
Busy working on docs and translations at the unconference venue.
Shaun worked on a new publishing system for help.gnome.org that could replace the current library-web scripts requiring release tarballs to get the content updated. The new platform would be a Pintail-based website with (almost) live content updates.
Localization-wise, there was some discussion around language packs, L10n data installation and initial-setup, spearheaded by Jens Petersen. While in gnome-getting-started-docs, we continue to replace size-heavy tutorial video files with lightweight SVG files, there is still a lot of other locale data left that we should aim to install on the user’s machine automatically when we know the user’s locale preference, though this is not quite what the user’s experience looks like nowadays. Support for that is something that I believe will require more input from PackageKit folks as well as from downstream installer developers.
The docs team also announced a change of leadership, with Kat passing the team leadership to me at GUADEC.
In other news, I announced a docs string freeze pilot that we plan to run post-GNOME 3.26.0 to allow translators more time to complete user docs translations. Details were posted to the gnome-doc-list and gnome-i18n mailing list. Depending on the community feedback we receive, we may run the program again in the next development cycle.
The docs team also had to cancel the planned Open Help Conference Docs Sprint due to most core members being unavailable around that time. We’ll try to find a better time for a docs team meetup some time later this year or early 2018. Let me know if you want to attend, the docs sprints are open to everybody interested in GNOME documentation, upstream or downstream.
At the closing session.
Last but not least, I’d like to say thank you to the GNOME Foundation and the Travel Committee for their continuous support, for sponsoring me again this year.
The GNOME documentation team started planning the next docs hackfest after some (rather long) months of decreased activity on that front. The previous docs sprint was actually held in Cincinnati, OH, in 2015, produced lots of content updates and we’d like to repeat that experience again this year from August 14th through 16th, 2017.
As with the previous event, the 2017 docs sprint will happen right after the Open Help Conference, which is returning this year thanks to Shaun.
What we want to do differently this year is extending invitation to all people interested in GNOME content, whether it is upstream or downstream. We would especially like to see some Ubuntu folks attending. With Ubuntu moving to upstream GNOME, we are already seeing an increased number of docs patches coming from Ubuntu contributors, which is great, and I think having a joint documentation event could strengthen and expand the connections even more!
I’m back from GUADEC and wanted to share a few thoughts on the conference itself and the post-conference hackfest days.
All the talks including the opening and closing sessions and the GNOME Foundation AGM are available online. Big thanks goes to the organization team for making this possible.
The program offered one doc talk (Documentation: state of the union by Kat) and several unconference sessions; the sessions were something new compared to previous years.
In one of the sessions, Shaun gave a presentation onpintail, a site builder that lets you publish your documents from sources in Mallard, Ducktype, DocBook, AsciiDoc (the latter coming soon), and so on, using yelp-xsl, a package also used in GNOME Docs. We are hoping to see pintail deployed in the Fedora Documentation Project soon, to replace the aging Publican-based documentation website.
As for the lightning talk session, I was really impressed by Eleanor Blandford and her presentation skills, given the fact that she is only 10! Future GNOME hacker?
It was great to see GUADEC turning into a family-friendly conference. Several families attended and there was a children’s corner available right at the venue.
During the hackfest days, I mostly worked on squashing various documentation bugs and adding more Mallard test tokens into gnome-getting-started-docs.
Distributors: If your distro is shipping Firefox (and not Epiphany) as the default browser, please file a bug similar to #770013 so that we can add test tokens for your distro into the getting-started page on web browsing.
Jakub and I also quickly reviewed the current SVGs and remaining getting-started videos. Updates are coming in the next release! With Shaun, we had a look at pintail and its support for building the Fedora DocBook-based guides.
As this picture says, GUADEC 2016 was well-organized and successful, so yes, thank you again organizers!
So I’m here in Karlsruhe, Germany attending GUADEC 2016. Today was the second conference day with the GNOME Foundation AGM, which, as the tradition goes, included team reports. As for L10n & docs teams, the update from the GNOME Translation Project was given by Alexandre Franke and the docs update was given by yours truly.
If you are at GUADEC tomorrow, don’t miss Kat’s talk Documentation: state of the union with more detailed updates on what’s been happening in GNOME docs land over the past 12 months.
Starting Monday, we are having a GNOME docs sprint at the GUADEC BoF venue. Our primary goal is to work on GNOME Help updates for the upcoming stable release but come join us even if you are not a contributing writer yet. We will guide you through the writing process and gladly convert you into a successful GNOME writer!
Last but not least, big thanks to the GNOME Foundation for sponsoring me!
For quite some time, lightweightdocumentationformats have been a big thing in the world of open source community documentation. While corporate environments are not very eager to move from their (often) ancient documentation platforms due to cost concerns, it is usually less of an issue for a typical open source documentation project out there to migrate to a new format.
I’ve recently started converting one of the open source documentation suites that I contribute to from a Publican-based DocBook XML source into AsciiDoc, which has been getting lots of attention especially from developer-centric communities.
The semantics of AsciiDoc is based on DocBook and AsciiDoc draws its roots from this industry-standard XML language. This allows for an easy AsciiDoc to DocBook conversion. Sadly, when you need to convert your DocBook content into AsciiDoc, you are left with a number of conversion tools which are either unmaintained or have incomplete support for DocBook syntax. This is an important aspect to consider when you are planning to migrate your documentation to the new format, especially if your documentation suite is rather complex and features a rich set of syntax and semantics.
Preparing your XML document for conversion
From the tools available for the conversion task (pandoc + docbook2asciidoc.sh, docbook2asciidoc, and others), docbookrx seems to have the most complete support for DocBook syntax. It can preserve tables, included files and images, procedures, and so on. Not all DocBook elements are supported, though. Here is an (incomplete) list of elements I had to replace with sed:
It is always a good idea to use a version control system to track any replacements in your XML source files.
What is nice about docbookrx is that it prints a warning when it runs into an element that it can’t recognize. Some of the other converters just silently drop the unrecognised element, including the content inside it, which is something to bear in mind.
Using docbookrx.rb
Clone the docbookrx repo:
git clone git@github.com:opendevise/docbookrx.git
Copy the docbookrx.rb Ruby gem from the repo to the directory containing the XML files you want to convert.
Load the gem, specifying a root file of your document as the input file:
The hackfest was held at a lovely co-working place called Platform 53 in Covington, Kentucky, just across the river from downtown Cincinnati. During the three intensive days full of writing, the docs team managed to update tons of pages throughout GNOME Help.
Due to the timing of the 3.18.0 stable release, the updates, together with some updated translations, eventually landed in 3.18.1.
I mostly focused on updating user account, power, and printing help. These should be in a good shape now. There are exceptions, though, like documentation on enterprise login, which is pending some code-related updates.
Some of us struggled with getting a 3.18.0 up and running. We tried different build images from GNOME Continuous, Fedora, and openSUSE. While there seems to be a plenty of options at first glance, when it comes to being able to try out and preview the actual GNOME Desktop, I think there is still a long way to go.
Testing some of the cool features in 3.18 can get challenging, for example, automatic screen brightness that requires an integrated light sensor. I wish I had one!
The team had a profound discussion about restructuring some of the most visible topics and topic groups in GNOME Help. We made good progress, although some of the issues, including content duplicity, remain unresolved. Material for the next hackfest?
Shaun organized a team building event for us, we watched a baseball game at Great American Ball Park. Cincinnati Reds!
Big thanks to Shaun & Kat for organizing the hackfest, and the GNOME Foundation for sponsoring me!
View from Platform 53 towards Downtown Cincinnati.The baseball game in Cincinnati.
Although this somewhat slipped through the cracks, it’s never too late to socialize the notes taken by Nuritzi Sanchez of Endless Mobile fame during the L10n-i18n-Docs BoF we ran at GUADEC 2015 (many thanks for taking them!).
The notes for the GTP (translation) part are here:
In a nutshell, the BoF attendees, both translators and documentation writers, touched a number topics spanning from screenshot automation (a follow-up from previous year’s BoF) to onboarding, mentoring and improving the projects’ getting started material for contributors, to glossaries, style guides and similar resources.
If you are interested in any of those topics, please have a look.
Hope the notes can be reused as follow-ups in future i18n and/or docs meetings.
