The past two weeks on Ubuntu project docs, i.e. docs on how Ubuntu comes into being, have seen work on big content items, including an initial dump of Developer Membership Board (DMB) docs and guidance about the Proposed migration process. Aside from that, a bunch of smaller improvements as usual.
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…
Article series or how to deal with looong topics?
When working on the docs about Merges, as well as later about Proposed migrations, I was unhappy with having a really long article (upwards of 20 subheadings and an endless scroll to the bottom). Navigating to the individual sections would be cumbersome and orientation on the huge page difficult.
In view of the fact that these docs are unlikely to be consumed in a linear fashion (i.e. few people would read them like a novel from start to end), I wanted to have a way to divide the big topics into smaller chunks while still preserving a clear sense of a unifying structure for the larger umbrella topic.
With the Proposed migration docs, I’m proposing ‘article series’: a bunch of related articles that are represented in the docs navigation hierarchy as individual pages, but they also have an extra navigation element in the form of an info box that provides the glue that holds the larger topic together. It looks like this:
This box is included in every article of the series, so the user always knows where they landed if they navigate to any one of the included articles (be it from some other page in the docs, a web search, or an external link).
I ran the idea by @sally-makin who liked it, so this has already been merged. Let us know what you think. Suggestions for improvements are always welcome (or PRs even 
).
New docs
The following quick mentions outline what new content has been added or worked on.
Proposed migration
The work on ‘article series’ was done together with a huge amount of edits, additions (and cuts), and various formatting + mark-up improvements to the Proposed migration docs. I incorporated the stuff from the Ubuntu Maintainers Handbook, which formed the skeleton of the topic, and extended it by content from the wiki, as well as completely new content that I added to make things clearer or easier to follow.
Still more to be done in this area, but the foundation is in a solid shape methinks. Also, it led me to add some related content (e.g. on autopkgtest) that will need some editing love – but as that would really take me down a rabbit hole, I left that for some next fortnight.
Developer Membership Board (DMB) content
Sally has been busy getting the DMB docs into shape, so they could be included in the docs base – ready for subsequent work by @paelzer and @jchittum. This is very much WIP, but it’s great that Sally has managed to wrangle the content into a mergeable state.
Triage docs
Following a discussion with @jchittum, @schopin, and @enr0n, we realized that the very useful and needed guidance about bug triage had not been a part of our scope for the Project docs. Given that the guys identified triage as one of the best areas for new contributors to get started on, it had to be fixed.
Sally took it upon herself and added a section on triage taken from the wiki (it was only an initial import, so more work will be needed). Sally did this import as a part of her “phase 1” of the “streamlining the contributor journey” work. Once back from PTO, she’ll be paying attention to the bug fixing/patching pages and de-duplicating those.
Phased updates doc
Sally also moved the Phased updates doc out of staging – with the help of Skia who provided a technical review on the content.
Glossary
Not really a new thing, but worth noting that it’s the Glossary that has received a number of additions from community contributors. Aside from that, I also added a few new terms and improved the definitions of some existing ones. Thanks to @schopin for helping me wrap my head around some of the cryptic output produced by Britney.
(Who would’ve thought that wanting to understand things about Proposed migration would take me to reading Britney source code – and eventually at least getting a Britney glossary definition out of it ).
Housekeeping
As usual, some cycles were spent on improving the stuff under the hood. This time, I’ll highlight three things:
- Shortcut for links to Ubuntu Matric channels
- Do you remember how Matrix channel links are constructed? I don’t. I mean, common:
https://matrix.to/#/#devel:ubuntu.comwhat’s with all the hash tags and colons? So I added a link shortcut in the form of{matrix}`channel`, which is rendered as a link with this link test:#channel:ubuntu.com. And now I won’t even try to memorize that URL format. - ‘Community’ label for PRs
- As community contributions pick up pace, we want a simple way to filter for PRs authored by community members. In other docs repos, the way is to use a ‘community’ label in GitHub, which is what we now have in ubuntu-project-docs, too.
- Linkcheck only once a week
- The automated linkcheck, which checks for invalid links, is super slow, often times out, is prone to flagging false positives, and has generally been driving us nuts. Still, it’s a useful thing. But it was a bit too much to have it run on every PR, so I changed the GitHub Action to only run on the docs once a week.
Btw, in case you’re wondering how one descends down rabbit holes, it’s rather simple. For example, while making the linkcheck change described above (which took 2, ok, 4 PRs because I’m rash and won’t ever learn…, but don’t tell anyone), I remembered being annoyed that our spellcheck workflow still installs aspell even though we now use vale as the backend, so no need for aspell. I couldn’t help it but submit a fix for that in the documentation-workflow repo.
And that led to me realizing that our Makefile installs everything from our requirements.txt file when creating a venv for the vale-based spellcheck, which is silly because our requirements.txt has all kinds of Sphinx-related dependencies that vale has no use for. But I steeled myself and shelved that one. For now.
What’s next?
This week, it’s Sally’ turn for time off. When she returns, she’ll be talking to the release team about their docs. I’ll be taking some more time off during the last week of August, so it’ll only be to full strength in September. Meantime, I’ll use this week to fix things I’ve been wanting to do for some time.
How to contribute/get involved
- Technical review and update needed on the bug triage section (whole section).
- Lots of duplication on bug triage and bug types pages. It would be good to have the triage page contain the actual steps, and the reference info/explanation on bug types (so that bug types is more like the bug status and bug importance pages).
- Reviews and improvements to the bug-fixing and patching topics would be also super welcome.