This update wraps up the 25.10 cycle and the bulk of main work on the Ubuntu Project docs. There’s more to be done, and more blog updates to be posted, but this marks the last milestone of the major effort that we’ve undertaken to complete since around May this year. I’m proud to say that we’ve somehow managed to do all that we set out to do.
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…
- Ubuntu Project docs: post pit-stop push
- Ubuntu Project docs: Going (semi)official!
- Ubuntu Project docs: the final furlong!
Last fortnight
Before I get to the advertised project summary, here’s a quick, cursory recap of what we worked on in the past two weeks.
- Stable Release Updates (SRU) and Tech Board docs have been added to the repo and published; redirects from their old locations have been set up.
- @marek-suchanek contributed guidance about the packaging workflow used by the Ubuntu Desktop team (PR to be merged shortly).
- @karljs added more content to the Rust-specific packaging instructions and also contributed an article explaining the role of various tools packagers use.
- Backlog is being populated for next steps.
- @sally-makin added the bulk of Community docs:
- All pages under “docs” in the Community Portal have been moved.
- There is a plan for setting up the redirects, and Sally will be helping with that (after the company Sprint) to make sure it all goes smoothly (since they’re Discourse based it’s not as easy as for some other sets of docs).
- Sally also updated and fixed lots of links to get them to point to relevant places within the docs set as opposed to deprecated locations like the wiki or old guides.
Wrap up
This article summarizes the major accomplishments of the preceding six months, but it doesn’t want to suggest that all is done and dusted. We (and others) will continue working on the docs, polishing the content, adding things we haven’t yet added, and so forth. Work on docs is never done 
What did we set out to do?
The underlying goal of this effort has been to bring together most (if not all) the documentation that provides guidance on how the Ubuntu distribution is made (see also Revitalising Ubuntu Project Documentation). Instructions for contributors and maintainers, community guidelines, governance principles, various pieces of reference.
All this has historically been scattered around many different places, maintained (and abandoned and resuscitated and forgotten and duplicated and neglected, and updated, etc. etc.) in the Ubuntu wiki, packaging guides, team-specific handbooks, internal documents, random pieces of docs, and so on.
We tried to catalogue as many of these resources as we could identify, form a plan for putting them all together, and finally figure out what needs to be done to make it all a useful documentation set that could supersede all those legacy docs and become the Single Source of Truth for the creators of the distro.
Aside from developing the new docs set, we also tried to ensure the old places would be gracefully retired, so that the duplication and slow decay of content wouldn’t continue. To that end, Sally has been diligently maintaining a list of all places that would need redirects. As we’ve been migrating content from different properties (docs, wiki pages, …), we’ve also been either redirecting the addresses or removing the old docs to ensure people only find the new stuff from now on.
Project content
When it comes to the actual docs, the content we’ve been working with, the following are the highlights.
Navigation
Sally devised and prototyped a simple navigation hierarchy for the docs that reflects the different contribution paths (see Making sense of the contributor story). It allowed us to categorize the content in a way that has so far proved to be quite adept at presenting all project docs in one docs set.
The main challenge in this regard has been to make the various kinds of docs easily findable while recognizing that the guidance is for a number of quite different kinds of users – from potential community members looking to contribute for the first time to seasoned maintainers who have been uploading to the package Archive for years (and all those in between).
Migrating chief legacy resources
While as mentioned above, these docs used to be all over the place (and nowhere), there were several main caches of docs that we needed to consolidate:
- Ubuntu Maintainers Handbook
- Ubuntu Packaging Guide
- Ubuntu wiki (various pages and sets of pages)
- Specialty docs: SRU docs, Technical Board governance docs, git-ubuntu docs, MIR docs
- Community docs on ubuntu.com
All these have earmarked for migration. Sally and I divided them between us and worked on slotting all their content into the new docs set. I’m happy to report that all of the above have landed in the Project docs. Some bits and pieces still need work (editing, updating), and there are a few straggler pages in the wiki that have slipped through the cracks. But the vast majority of articles have been incorporated into the new docs set while their original locations have either been redirected/removed (or will be shortly).
Combining content from so many places involved lots of merging, de-duplicating, pruning, consolidating, and reorganizing. While a bit of a nightmare at times, it has been one of the most enjoyable parts of the whole process for me. Seeing the guides take form, adding missing bits and pieces, investigating what is obsolete, testing the procedures, and learning a lot throughout – these things have been the highlights.
This has been one the most time-consuming aspects of the work, and many thanks go to the many people who have helped us make sense of the content, prioritize, decide what’s relevant and what should be discarded, et cetera.
Editing, editing, editing
Did I mention editing? There was lots of it. Converting between source formats (wiki, rST, plain text to Markdown). Fixing existing mark-up and formatting, and unifying formatting for consistency. Editing out redundancies, jovial lingo, and duplicate content. Editing in cross-links, navigation elements, and semantic mark-up. Improving language, rewording headings, renaming files, … you name it.
Major workflows (such as merging, sponsoring, proposed migrations, and others) have been ‘serialized’ to form coherent content sets. This allowed us to present groups of articles in a manner that made navigation simpler and more intuitive than what we would have with just putting docs under the same category in the navigation hierarchy.
Crucially, it also gave us the opportunity to form article series from pages that come from otherwise unconnected parts of the docs set (so, for example, the sponsorship series groups articles for contributors seeking sponsorship and uploaders who do the sponsoring).
New docs
As we went along, we also identified a number of processes where documentation was either inadequate or missing completely. This meant either rewriting the content to get it up-to-date, or writing new instructions from scratch. Again, this involved many discussions with distro gurus on the Debcrafters, Foundations, and Server teams who helped us make sense of things and reviewed the new docs. Thanks!
There’s more to be done in this regard, too. As we’re wrapping up, we’re filing issues, so that the gaps we’ve encountered but couldn’t plug just yet don’t go forgotten or get overlooked again.
Meta work, aka the Project project
Aside from the work on content, we also wanted to make sure the new ‘Project docs’ are established as a viable project. In other words, we put thought and effort into ensuring that this new documentation set can continue serving its purpose even when we’re not giving it our 100%.
To that end, we worked to put these main pieces of the project puzzle together:
Robust contribution guide
Our ‘docs about docs’ are in place. The contribution guide outlines basic documentation principles, lays down ground rules for participation, and provides guidance on how to get started contributing. The docs set introduces a bunch of simple mark-up enhancements, which are also described in the guide for contributors.
ACLs for ‘special’ teams
Given the governance structure of the distribution stewardship, there are a number of teams that require ownership of documentation that pertains to their particular area of responsibility. In order to be able to include such docs in the Project docs set, we created a simple system that ensures these teams keep control over ‘their’ content while still having it in the same repo and published as parts of the larger docs set.
The members of these teams have been made owners of their respective pieces of content in the repo through the CODEOWNERS mechanism. Big thanks to all those who have made themselves available as reviewers (and approvers) in this way. Without them, this entire concept of consolidated docs would only go half way. As a bonus, this has allowed us to forge a sense of ownership and maintenance responsibility that should help with keeping the docs up-to-date and relevant.
Community involvement
Ultimately, this documentation is for the Ubuntu community. We want to make it easy for members of the community to get involved, start contributing, and be a part of the Ubuntu story. We welcome contributions, be it in the form of feedback or content.
We have used the framework of the Open Documentation Academy to invite new contributors (a bunch of contributions through that channel have already been merged). And we have tried to make sure the whole project is being worked on transparently, so we have been publishing these fortnightly Discourse updates.
What now
Party! 
Well, almost 
As I said above, the work continues. But that won’t stop us from feeling all smug about a job (mostly) well done. There’ve been some bumps along the way, but on the whole, I’m quite happy with the way things have gone. Massive thanks to my main collaborator, Sally, for being so fun to work with, for keeping me honest, and for selflessly stepping in whenever I asked.
Get involved
We keep saying this, but now more than ever, your feedback is important. Use the docs, test the procedures, find weak spots, file issues, submit PRs. You know the drill. Thanks for all your input so far. Keep it coming.