The past two weeks in the realm of Ubuntu Project docs have been mostly about cleaning stuff up, making sense of things, and generally working with the massive amount of content that we’ve brought over from the Ubuntu Maintainers Handbook (UMH) and the Package Guide (PG) – see Sally’s previous update where she described the context and what we’re doing with this content: Ubuntu Project docs: Will it blend? In addition to that, we’ve done a bit of housekeeping as usual and added some nifty little things to make the project a bit friendlier for maintainers and contributors.
Are you wondering what all this is about? Check out our entire article series:
Ubuntu Project docs
- Bringing together 20 years of documentation
- Ubuntu Project docs: MIR, ACLs, and more
- Ubuntu Project docs update: making sense of the contributor story
- Ubuntu Project docs: welcoming our first contributions!
- Ubuntu Project docs: Will it blend?
- Ubuntu Project docs: Sorting things out
- Ubuntu Project docs: Piloting ‘article series’
- Ubuntu Project docs: Another day at the office…
Sorting through it all
One of the main problems with the existing Ubuntu project documentation – aside from docs that are just plain missing – has been the duplication of content. This includes guidance that variously overlaps or procedures that diverge in what they recommend based on their authors’ different preferences, time when they were written, or team context that informed them.
While we have put substantial effort into sorting some of this out during the time the PG and UMH were in our staging area, the plan has always been to iterate on the volume of content as a whole once it’s promoted to the new, consolidated ‘Ubuntu Project docs’. So, that’s what has been keeping us busy for the past two weeks and will continue to do so for some time to come.
Ubuntu Maintainers Handbook
Sally has landed the bulk of the UMH content in the main part of the repo (this included converting it to MyST, updating all the links to still work in the new setup, and doing some basic edits and improvements for clarity – with a view to doing a whole lot more of this in the upcoming weeks).
This migration has prompted a major overhaul of the contributor-packaging sections: de-duplicating content from the PG, UMH, and the wiki, streamlining the instructions, and better highlighting contribution paths.
Processes & concepts
In a similar vein, I worked on reorganizing and de-duplicating the content we have about distro-maintenance processes and concepts. I’m now much happier with the organization, but there’s still work to be done on cross-linking the articles and – most importantly – ensuring that all this explanatory or referential process & concept stuff is well supported by actual practical instructions on how to do it.
Merges
I also spent a considerable amount of time editing the article on merging (packages from Debian to Ubuntu). This involved lots of language, formatting, and mark-up fixes and improvements, as well as updating links leading to other articles and vice versa. The instructions have been streamlined or expanded as needed.
There’s more to be done on this piece of content. In particular, I want to figure out a better structure because the article is too long, and given the extremely large number of steps, the flow is hard to follow. Right now, the article has sections doubling up as instruction steps, which is confusing (not to mention unwieldy). These sections are usually too long to work as items in a numbered-list procedure, but they’re also too granular to make sense as individual sections. This needs fixing.
I will also be incorporating more contextual info from the wiki (https://wiki.ubuntu.com/UbuntuDevelopment/Merging/GitWorkflow), and I will be trying to make sure the git-ubuntu flow is well rounded and coherent – because it still feels a bit disjointed now.
Housekeeping
A bunch of improvements happened on the publication side, and we also improved the guidance for contributors.
Repo best practices
Sally and I agreed on a number of basic rules to keep the docs sources consistent and make maintaining the repo simpler. Uniform ways of formatting the sources and keeping true to an invariant system of naming things makes it easier to navigate the sources and work with the mark-up. I added a description of these to the contributor guide. Specifically, we want to have the following consistent:
- headings
- anchors
- file names
(See Organization principles for details.)
Linking Launchpad
Another thing to make contributions simpler and source-reading easier on the eyes is utilizing the Sphinx extlinks extension to have custom roles for external web links. For now, I have added two roles: lpbug and lpsrc. These allow for easy linking to Launchpad bugs and Ubuntu packages on Launchpad respectively. For example, {lpbug}`1` automatically creates this link: LP: #1. For more, see Special roles for links.
Starter Pack update
The Sphinx Docs Starter Pack is a Sphinx extension we use to get some handy docs authoring and publishing capabilities out-of-the-box and to ensure our documentation-publishing methods stay reasonably consistent across the board.
Recent updates to the Starter Pack warranted an upgrade to the latest version, so I took care of that last week. A highlight is the new spellcheck (used both for offline, local checking, as well as in our CI that runs as a GitHub Action). The check is now based on vale, which offers many improvements over the pyspelling module we previously used. Namely, the speed of the check is an order of magnitude better, and the checking is performed on the markdown source of each page – not on the resulting HTML – which makes much more sense. The output report is also a lot easier to read, with a summary highlighting errors.
What’s next?
In the upcoming two weeks, Sally will start iteratively putting in the mentioned improvements to the contributor docs. I will start on Proposed migrations docs but will also continue to improve the Merging docs as outlined above.