A 2019 documentation hackfest update

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.

GUADEC 2018

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.

GUADEC 2017 Notes

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.

Plans for the next GNOME docs hackfest

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!

GNOME docs
GNOME docs are a friendly bunch of people!

Interested? Let us know! I’ve set up a wiki page with details on the event where you can sign up and propose your own ideas for agenda.

As always, you can find GNOME docs folks in #docs on irc.gnome.org.

Hope to see you all at the sprint!

GUADEC 2016

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.

20160813_172452If 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.

20160813_172544Starting 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!

badge-goingtoLast but not least, big thanks to the GNOME Foundation for sponsoring me!

sponsored-badge-shadow

Converting DocBook into AsciiDoc

For quite some time, lightweight documentation formats 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:

  • productname
  • menuchoice → menu:examplemenu[examplesubmenu > examplesubsubmenu]
  • guimenu → [label]#example#
  • guisubmenu → [label]#example#
  • guimenuitem → [label]#example#
  • userinput → [userinput]#example#
  • option → `example`
  • systemitem → `example`
  • remark
  • revhistory

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

  1. Clone the docbookrx repo:
    git clone git@github.com:opendevise/docbookrx.git
  2. Copy the docbookrx.rb Ruby gem from the repo to the directory containing the XML files you want to convert.
  3. Load the gem, specifying a root file of your document as the input file:
    ruby docbookrx.rb Admin_Guide.xml > Admin_Guide.adoc

    The gem will follow included files referenced from the root file and convert the whole document.

  4. Run asciidoctor to generate an HTML preview:
    asciidoctor Admin_Guide.adoc

Some additional clean-up of your document is usually needed afterwards but the document’s overall structure and syntax should be preserved.

Open Help Conference 2015 Hackfest Wrap Up Notes

Wrap up notes for the Open Help Conference 2015 GNOME Documentation Hackfest, Cincinnati, OH, September 28 – 30, 2015.

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!
  • I managed to get the Getting Started module in sync with most of the updates that landed in GNOME Help. Meanwhile, Jakub has been working on a different approach to Getting Started animations.
  • 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.
View from Platform 53 towards Downtown Cincinnati.
The ball game in Cincinnati.
The baseball game in Cincinnati.

sponsored-badge-simple

Notes from L10n-i18n-Docs BoF

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:

https://wiki.gnome.org/TranslationProject/GUADEC2015NOTES

And the documentation part notes are here:

https://wiki.gnome.org/DocumentationProject/GUADEC2015Notes

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.

Open Help Conference 2015

I’m here again in Cincinnati, OH for the 2015 Open Help Conference and GNOME Docs hackfest. The venue for this year’s conference is at the beautiful Mercantile Library in downtown Cincinnati.

20150926_09091820150926_095604The area around Cincinnati has a strong German heritage, so no wonder the library also features some German manuscripts. Reminds me of my years spent studying paleography.

20150926_12185120150926_095630The Open Help Conference is not like one of those industry conferences with large numbers of participants but the attendees here are, on the other hand, very focused on the specific topic of open source documentation and docs community management. It’s always cool to see how other communities approach community docs, and learn some new tricks along the way.

20150926_12195420150926_121324Great to see old faces again, and meet new ones. I’d like to thank the GNOME Foundation for making it possible for me to attend the conference and hackfest.

20150926_122040sponsored-badge-shadow

Running a Docs Workshop at DevConf

With Bara Ancincova of Red Hat docs fame, we ran a docs workshop at this year’s DevConf in Brno. It was mostly a follow-up to to a Fedora documentation hackfest held at Flock 2014 in Prague. Quite a few people showed up Saturday afternoon, which was a nice surprise, given that docs sessions are usually not among the most attended at a technical conference.

Some of the topics we touched included:

  • DevAssistant. Slavek Kabrda joined us to give a short presentation about what DevAssistant has to offer when it comes to kick-starting your projects. Based on the ideas we first explored at Flock, Slavek and Jaromir Hradilek started to hack on a new assistant that will mostly serve people who are getting started with DocBook, the Publican toolchain, and Fedora documentation. However, there is nothing preventing us from making a step further and including support for other documentation projects, formats, and toolchains, if there is interest (and people willing to help out).
  • The plan is for DevAssistant  to be able to create a complete writing environment that would let you set up a basic structure for your new documentation project, with templates and different content types.
  • DevAssistant works well in both CLI and GUI mode. While developers and some documentation writers might prefer to work on the command line, newcomers often prefer a GUI option. Both options, however, provide an integrated solution that lets you work within a single app (and write in a text editor of choice). This means that DevAssistant aims for both the developer and documentation writer audiences, which often overlap anyway.
  • Building documentation. We talked about Jenkins, which is typically used in a software development environment.  Since Jenkins can run pretty much any commands available on the server, it can also easily be used to take care of your continuous documentation builds. This makes docs QA’ing and reviewing so much easier.
  • Pavel Tisnovsky is working on Jenkinscat, a dashboard for Jenkins to let you easily manage documentation builds.
  • Publishing documentation. This is a long-standing issue in Fedora. We explored the idea of using Jenkins and Jenkiscat for Fedora.
  • Testing your documentation. In this segment, Jaromir Hradilek talked about Emender, an emerging test automation framework for documentation. Its goal is to allow you to run a number of tests against your (semantic) documentation. Ultimately, this can save tons of time on the docs QA front, especially when you are maintaining a huge and ever-increasing number of documents for different projects or products.

A number of great ideas were put forth for future documentation events which I hope we could organize later this year.