I know I usually end with a story, but today let’s start with one – all about the Ubuntu Packaging Guide, the Ubuntu Maintainer’s Handbook, the wiki, and our quest to bring them all together.
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…
How we got here
The original Ubuntu Packaging guide (packaging.ubuntu.com) was an absolute treasure trove of information in the early days. However, much like the wiki, it suffered at the hands of time, and up until a few years ago it was being kept on life support by the Ubuntu community.
Its plight was brought to our attention when the infrastructure hosting it was due for deprecation, and rather than let it slip away into the abyss, it was rescued by the herculean efforts of @dviererbe and aided by the community (including Robert and myself, of course).
This means that the existing material around packaging, seeded by the original Packaging Guide, updated and enhanced over the last two years, now forms a solid and well formed set of documentation to teach people about packaging.
However, in that intervening period, the Ubuntu Server team created and kept a set of internal documentation (the Ubuntu Maintainer’s Handbook) around the different packaging processes. It was internal, in the sense that the team created it for themselves to help onboard newer team members – but it was always public, and it became popular among Canonical engineers to learn packaging through “doing”.
Current state of play
What this has given us is two semi-overlapping sets of documentation that we need to blend together in a way that feels seamless. This has been the current focus for both Robert and I over the last two weeks, and will be for the next two as well.
Packaging Guide
Since Robert returned from vacation, he has not only reorganized the entire Packaging Guide to fit our new structure, but he’s also implemented a host of other improvements while doing so, from streamlining and fixes to formatting improvements and language edits.
What this means is that the Packaging Guide content can now be found in the main documentation – filling in most of the gaps in the “how Ubuntu is made” section, detailing the processes and the key concepts, and the “contributors” section, giving detailed step-by-step guides on how to contribute package changes.
Ubuntu Maintainer’s Handbook
Now, with the Packaging Guide content in the main docs, I can begin to fold in content from the Maintainer’s Handbook. Behind the scenes, I’ve been preparing for this by identifying content and where it should move to, as well as changing the formatting from standard/GitHub markdown to MyST and other supporting changes.
This is complicated by the fact that the UMH heavily references the wiki, rather than the Packaging Guide, so there is also more content to bring over from the wiki. Identifying and preserving the correct links in each case has to be done quite carefully, to make sure that readers are directed to the material they’re expecting. While I’m doing this, Robert will continue to improve and iterate upon the Packaging Guide materials, particularly focusing on proposed migration.
Housekeeping
Now that we finalized the move of the Archive Admin docs, I’ve updated the old wiki pages with links to the new documentation. Since these pages are heavily referenced, I used deep linking rather than redirects to preserve the headers.
Robert has been investigating automating syncs between Launchpad and GitHub teams to have LP-based access control in GH – for teams that need code ownership over certain topics, such as the MIR team. Until now, we’ve been adding individuals to ensure the right people are asked to review changes, but having automatic access controls would be much better!
How to contribute/get involved
@Sebastian from the Community team recently kickstarted an initiative called “listening to contributors”, where they set up sessions to connect with community members to hear directly from them about their experiences of contributing. This sounded really interesting to me, so I attended both of the sessions that have been held so far (there are more to come!).
Firstly, I’d like to thank the community members who generously volunteered their time to talk to us – the insights they gave us were so valuable, and I was able to distribute actionable feedback to other teams as a result, too. I personally gained a lot of insight into what the tester experience is like, and I hope to work closely with our testing community over the next couple of months to help improve the learning experience for new testers especially.
Whether you contribute code, documentation, translation, or test code – if you would like to speak to our community team about your contribution experiences, please fill in this form to indicate your interest.
And as always, if you’d like to contribute to the Ubuntu Project documentation directly, you are very welcome! Check out our contributing page for more details. If you’re new to contributing and want extra support and guidance, Robert and I are both involved in the Canonical Open Documentation Academy as well.
Thanks in advance for your help 
Story corner: data-driven fun
One of my favourite hobbies is looking at analytics. Now that the Ubuntu Project docs have been available for the last two months, I’ve added it to the list of repositories I monitor. With Read the Docs, we get basic (highly anonymized) traffic and internal search data, so I thought it might be interesting to share what we see so far.
Our top 10 pages (last 30 days)
Unsurprisingly, the MIR pages feature heavily in the top 10 – mainly because they were the first set of complete documentation to be fully migrated, so they’ve been around for the longest. However, the brand new +1 maintenance page contributed by @schopin is already proving popular.
Traffic trends
Most documentation sets, once they get established, follow a consistent pattern with low traffic on weekends, peaking at the middle of the week, and then falling back again (highlighted with the red curvy line). We’re not at that stage yet, so our traffic pattern is a bit more changeable than that, with Mondays and Fridays being about equal!
On the 3rd of July, a random Tuesday, we had double the expected amount of traffic (circled). I haven’t been able to figure out what was special about that day, yet 
Unexpected 404s
Another useful thing Read the Docs reports is “pages people have tried to access that returned 404s”. There are an unusually large number of pages that were 404ing following our moving documentation to the new organizational schema, and following moving pages out of the staging area and into the main docs.
What this tells me is that people have been bookmarking pages even at this early stage of the migration; definitely far earlier than we expected!
It’s fantastic that people are using the docs and finding them useful enough to bookmark – but that usefulness is undercut if you receive a 404 instead of a redirect. As a result of this data insight we’re going to add redirects for the most popular 404ing pages. More than that, to provide a better experience from now on we’ll be a bit stricter about adding redirects when we move pages around– even for work-in-progress pages in the staging area. Thanks for your patience so far!