The Road to New Xubuntu Docs

Two years, eight contributors, and numerous Zoom meetings resulted in over eighty commits refreshing our user docs. All in time for the 22.04 release.

The new Xubuntu documentation is finally complete. Two years, eight contributors, and numerous Zoom meetings resulted in over eighty commits refreshing our user docs. Incredibly, we managed to land all of the updates in time for the Xubuntu 22.04 “Jammy Jellyfish” release. Here’s how we got here.

A section from the “What is Xubuntu?” chapter of the new Xubuntu docs.

Doing Things Differently

In April 2020, Yousuf reached out to the Xubuntu Development list interested in kicking off some discussions around contributing to Xubuntu documentation. Our previous documentation lead, David Pires, had been offline and unreachable for nearly a year. I agreed to meet with Yousuf in David’s stead. Our first Zoom meeting led to a plan: copy all existing documentation to Google Docs, collaborate on the updates, and apply the changes to our official docs.

The next several weeks consisted of a series of weekend Zoom meetings, Telegram discussions, and lots of documentation edits and reviews. The team consisted of myself, Yousuf, and six other contributors, most of them new to contributing to Xubuntu. Our contributors came from a variety of backgrounds: history, education, networking, software development, and politics (and that’s just what I gathered from our normal conversations)!

A mockup of the new language selection buttons for the Xubuntu docs homepage.

We worked on a chapter at a time. Yousuf would write up the changes, the team would mark them up, and the following weekend we would review, discuss, and apply those changes. We also discussed updating the homepage to modernize the language selection and updating the CSS to better match the current Xubuntu website. Those changes were ultimately scrapped due to time constraints and relative disinterest in that area. As the chapters were completed, we started working on porting the content back to Docbook. This porting process proved to be especially confusing and time-consuming.

Docbook, Work Harder to Publish More Easily

Docbook: A section with a title, two paragraphs, and an image requires a lot of code.

Docbook is an XML-based documentation solution that Xubuntu has used for years to produce its user and contributor documentation. It enables us to easily output our documentation in HTML or PDF format so users can easily get the help they need, even offline. The tradeoff is that the format is difficult to get used to and ultimately led to me converting 95% of the docs to the Docbook format by myself. There were some early attempts by the team to port the documentation, but with a litany of unresolved schema validation issues, interest and contributions waned.

If your code does not pass Docbook’s strict validation, prepare for an intimidating error log that references the wrong file and line.

That said, it wasn’t all bad news. Along the way, I learned more about GitHub Actions and GitHub Pages and implemented an automatic testing and deployment workflow. With each new commit or pull request, the submitted code was built and tested, and successful builds were automatically deployed to for review. These workflows are now a permanent addition to the Xubuntu Documentation and will make it easier to perform code reviews and make sure translations continue to pass validation. And if you want the latest and greatest version of the docs, you can find them in one place.

Getting It Done

Fast forward to this year and the urgency of an impending LTS release. Over the course of a few weeks, I finished converting the docs and pressed others for reviews. The team offered some quality feedback which helped the docs get to an acceptable level. Just days before Final Freeze I was able to merge, package, and upload xubuntu-docs 22.04. And you can use it today, with the exception of one remaining issue: Snap package confinement.

Attempting to load the new Xubuntu Docs today will show a “File not found” in the Snap-packaged Firefox or Chromium browsers.

With the release of Ubuntu 22.04, all flavors are now using the Firefox Snap package. Snaps are sandboxed, preventing access to most system resources and files. Unfortunately, this also blocks access to the Xubuntu Docs, LibreOffice Help, and many other files that should be accessible. A fix has already been applied to snapd and should be landing in the next couple of days. In the meantime, if you want to access the docs you can visit the online docs or load the PDF version from /usr/share/xubuntu-docs/user/C/xubuntu-documentation-USletter.pdf in Atril.

Getting to this point was a long and exhausting journey. I’m grateful to our new contributors for stepping up and bringing our documentation back to a great place. That said, I hope I never have to work with Docbook again. It’s tedious, and if you’re the only one working on it, it can suck up all of your time just getting your code to work. Here’s to hoping it stays maintained this time from community contributions. 🤞