The Road to New Xubuntu Docs

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.

Doing Things Differently

In April 2020, Yousuf contacted the Xubuntu Development list and expressed interest in discussing 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 Yousuf, me, and six other contributors, most of whom were new to contributing to Xubuntu. Our contributors came from various backgrounds: history, education, networking, software development, and politics (and that’s just what I gathered from our normal conversations)!

We worked on a chapter at a time. Yousuf would write up the changes, the team would mark them up, and we would review, discuss, and apply those changes the following weekend. We also discussed updating the homepage to modernize the language selection and updating the CSS to match the current Xubuntu website better. 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 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.

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. The submitted code was built and tested with each new commit or pull request, and successful builds were automatically deployed to https://xubuntu.github.io/xubuntu-docs/ 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 reach an acceptable level. Just days before Final Freeze, I was able to merge, package, and upload xubuntu-docs 22.04. You can use it today, except for one remaining issue: Snap package confinement.

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 land in the next few 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 returning our documentation 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. 🤞