Summary: The Ubuntu Desktop documentation is scattered across too many websites. We’re consolidating it in one place, updating it and moving to standardized tooling, similar to the rest of Ubuntu documentation. The result will be easier to read.
The user experience
Where do you go when you need to learn how to do something in Ubuntu, specifically for Desktop usage?
-
If you wanted to Install Ubuntu Desktop or Upgrade Ubuntu Desktop, you’d go to the Ubuntu Tutorials site; or, more likely, a search engine would point you there.
-
If you wanted to Install languages or Add a Personal Package Archive (PPA), you’d arrive on the Ubuntu Help website, which currently claims to be the official Ubuntu Desktop documentation.
This is also the same documentation that you get when you open the Help application in Ubuntu.
-
If you were interested in Switching To Ubuntu From Windows or enabling Accessibility features, you could find yourself on the Community Help Wiki.
-
For NVIDIA drivers installation, you’d use the Ubuntu Server documentation.
Unless you use a search engine, you really have no way of knowing where a topic is covered. We have too many different sites with no clear boundaries, and every one looks different. Most Ubuntu users probably don’t even know them all.
What’s worse, a lot of the content there is severely outdated. An article that was written in 2017 could have been really useful back then. However, it might still assume that you’re using components that no longer exist or are being replaced, like X.org.
The contributor’s inconvenience
Say you notice one of the outdated pages and you want to update it. Every one of the documentation sites has a different workflow, markup language and permissions to do it. You’ll deal with technologies ranging from the MoinMoin wiki language to Markdown, and problems ranging from unreliable login to the lack of version control.
You’ll also encounter Mallard, which is the XML-based markup language used for the GNOME documentation. The Ubuntu Help website – the official Ubuntu Desktop documentation – is actually a fork of the GNOME documentation (gnome-user-docs), adding 19 pages about Ubuntu Desktop to 307 pages about GNOME.
On its own, Mallard is actually rather nice. Unfortunately, its tooling is unmaintained, its website, where you learn how to write Mallard, is offline, and the Help application, which renders Mallard documentation on the desktop, is also unmaintained and no longer suitable for the containerized ecosystem where GNOME and Ubuntu are heading.
GNOME is now also looking for a new solution. See the GNOME announcement: Updates from the release team.
Even if you know Mallard, the Ubuntu documentation repository is tricky to use. When I said that it was a fork of GNOME documentation, I lied. In fact, it’s a separate Git repository called ubuntu-docs on Launchpad. This repository hosts the 19 pages about Ubuntu, along with scripts that merge the GNOME pages with the Ubuntu pages to produce one documentation set at the level of Deb packages. The repositories were split to enable documentation translations between upstream and downstream.
In order to publish this documentation on Ubuntu Help, you have to install the Deb packages with GNOME and Ubuntu Mallard documentation, convert them to HTML, and commit the HTML files to the help.ubuntu.com Bazaar repository on Launchpad.
The impact on the content
All of this results in a lot of overhead: learning how to edit the documentation, doing the manual tasks, chasing the right maintainers, watching out for inevitable duplication.
The effect is that the Ubuntu Desktop documentation moves very slowly, becomes outdated and misleading, and the documentation community is discouraged from contributing, apart from a few heroic individuals like @dsmythies (Thanks for all your work!).
When a new Ubuntu feature is developed that needs to be documented, everyone avoids describing it in our “official” Ubuntu Desktop documentation. Instead, people write Ubuntu Tutorials, blog posts or other kinds of content, which doesn’t help the situation, but I don’t blame them.
In short: it’s unreasonably hard to document Ubuntu Desktop.
What we’re doing instead
You might be asking: Why don’t we just consolidate all this documentation on one website that’s based on well supported technology? And indeed, that’s what we’ve decided to do.
I joined Canonical as a Technical Author in February. After analyzing the state of things and discussing it with the Desktop Team, I’ve decided to set up a new documentation project for Ubuntu Desktop. It’s based on the Read the Docs platform, which is used for the majority of Ubuntu and Canonical product documentation, together with Discourse.
I’ve been building the new documentation set. You can already browse it online at Ubuntu Desktop documentation. The new documentation is written in Markdown, specifically in its MyST implementation. It’s developed in GitHub and built with Sphinx.
This new documentation is still incomplete. The first thing we did was write accessibility documentation, which you can consider the showcase of our vision.
Unfortunately, this means that we can no longer just reuse GNOME documentation: we’ll reuse and rewrite some parts of it, integrating it with the larger Ubuntu Desktop documentation. We believe that the pros outweigh the cons.
How it’s better for users
Eventually, there will be just one place to look for Ubuntu Desktop documentation. Thanks to the focused work that we’re doing, we hope that the new documentation is much easier to navigate, more pleasant to read, more up-to-date and generally more useful.
The content is also being rewritten with the Diátaxis framework and style guide in mind to increase the quality of the documentation.
How it’s better for contributors
GitHub is the standard for open-source collaboration. It’s well known, it’s reliable and it has great collaborative features.
Markdown is the most widespread markup language in the open-source world. It’s simple and easy to learn, while MyST adds many features turning Markdown into something that you can use to build complex technical documentation.
For contributors, this setup is much easier to use compared to the previous Ubuntu Help solution, and it enables us to iterate on the documentation more quickly.
If you’d like to contribute, we’d love to have you join us! Just give us a little time for the new documentation to settle down first.
What about the offline help?
Ubuntu Desktop still comes with the Help application that renders the Ubuntu Help documentation. We’re looking into replacing it, too. Stay tuned.