Picking up right where we left off a month or so ago. We’ve resolved to continue providing fortnightly updates on the happenings in the space of Ubuntu docs in general. To that end, @sally-makin (Ubuntu Server) and @rkratky (Ubuntu Foundations) have roped in our friends on the Ubuntu Desktop team (@shanecrowley, @marek-suchanek) and also @yhontyk who has been helping to rehome the neglected Ubuntu tutorials and with community efforts.
Ubuntu Project docs: where are we?
During the last six months, we’ve kickstarted the effort to consolidate all docs about making Ubuntu in one place and provide one source of truth for contributors, maintainers, and all interested in the behind-the-scenes workings of the distro. Read the summary of that work here: Ubuntu Project docs: That’s a wrap!
The following six months will see us polishing the content, fixing the myriad issues, adding yet more content that was left behind, and generally trying to make the docs set as solid as possible.
In the past two weeks, I’ve added a number of bugs to the queue to have a backlog of what needs to be done. If you have an idea of your own (important piece of content not yet migrated, or an article in need of an update, file a bug, too, please).
We’ll be also continuing our effort to bring the project to the community by inviting contributions and participating in the Open Documentation Academy.
The one source of truth. Or is it?
An interesting question has come up when @mwhudson submitted a PR (package-archive.rst: go into more detail about what can go into multiverse) that updates and improves some of the languages (in the Ubuntu Project docs) that defines what goes into the Multiverse component of the Archive.
@rbasak pointed out that this should really be defined by the Ubuntu policy Manual (which lives in the ubuntu-policy package). So, either the wording of the Policy should also be updated accordingly, or the docs shouldn’t diverge from the Policy.
However, as it happens, the Policy has not been updated since 2009, which poses a question: is it still relevant? And what should really be the one source of truth if the Policy seems to be somewhat neglected?
I asked that question in the ubuntu-devel mailing list (ubuntu-policy: still needed/valid?), and I’m curious where the discussion will go. For us docs people, it’s important because, ideally, we’d like the docs to be in accord with the official word on all such matters, but it would also be nice to not have to repeat this in multiple places.
Ubuntu Server
@sally-makin is getting ready to upgrade the Ubuntu Server docs to the newest version of the Sphinx starter pack (from quite an old one). This update will bring the styling of the docs into line with newer sets like the Ubuntu Project and Ubuntu Desktop docs.
The Server team is using this as an opportunity to do a quality refresh on the documentation as well, so after this change they’ll be activating automated checks on the spelling, links, etc.
In December, we’ll also see a change to the docs URL to ubuntu.com/server/docs - please keep an eye out for this. Everything should be redirected automatically, but once the change happens, you may want to update your bookmarks.
Ubuntu for Developers
In the upcoming months, we’ll be adding a how-to guide on installing and a tutorial on basic use of the Zig toolchain. Stay tuned!
Aside from that, we’ll also continue to keep the docs up-to-date and add new material.
Ubuntu on WSL
See: Ubuntu on WSL documentation
We are preparing for the official launch of Ubuntu Pro for WSL. This Windows application will initially launch with support for automated Pro-attachment of Ubuntu instances running in WSL.
To support the launch, we have been making improvements to our Pro for WSL guides and security documentation, and working on more cleanly separating features that are only available to beta testers.
Features that are available to general users will be documented in the stable version of the documentation, while those available to beta testers will be in the latest version.
What’s next
Before the mid-year break, I’d like to get a start on a number of issues, but most importantly, I’ll attempt to fix all the various issues we now have with the automatic docs checks (mainly spellcheck and inclusive-language check).
For one, we have cut some corners when importing large amounts of content, so the checks are disabled for certain parts of the repo. Secondly, the spellcheck turned out to be incorrectly configured in our Starter Pack, which resulted in many mistakes being overlooked. The check has now been fixed, which has left us with a rather ominous amount of mistakes to be corrected.
Get involved
As usual, your comments, feedback, bugreports, and PRs are most welcome.