Greetings from sunny(ish) Britain! Robert is enjoying a well-deserved holiday, so it’s my turn to give a progress report for the Ubuntu Project documentation.
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…
Community contributions
In Robert’s previous post, he mentioned that we’ve signed up the project to be part of the Canonical Open Documentation Academy (CODA). To kick things off he constructed a great set of issues perfectly suited for people making their first contributions in open source projects, and over the last two weeks, all of them have been picked up by CODA contributors! Thanks to the whole CODA community for such a warm welcome, but especially to st13g and jade-abc for your great work so far – we really appreciate it 
Speaking of contributions, we’ve seen a major flurry of activity in the MIR section. Now that we finished migrating the MIR content, the team has taken the opportunity to improve their content even more. Pull requests and issues are coming in thick and fast, from both the team and the community – @slyon has done an excellent job of keeping on top of reviewing them all 
As a side bonus to all the team’s hard work, this has given us a really thorough test of the code ownership setup, and after a few more tweaks, is now working exactly as expected.
@schopin has also contributed a brand new page on the +1 maintenance program to guide participants 
He’s also been a massive help to me over the last few weeks – I’ve had a million questions (or so it feels) about packaging, and he’s been answering them with endless patience and good humour. Thanks for all your help!
Archive Admin docs
For myself, I’ve been working on the Archive Admin docs, which have now landed! 
This has been a mammoth effort over the last month that couldn’t have been completed without the expertise and guidance of @paelzer. What started as one page to migrate turned into quite a few more than that as we pulled in page after page of related content as well. We’ve done a thorough review of the old wiki content and overhauled it; we kept what’s already good, updated what needed help, and reorganised it all to fit our new structure (more on that below!).
The main landing page is about the Archive Admin team themselves. The majority of the content is in the maintainer guides section, outlining all the tasks and duties and how to complete them, mainly for the benefit of new Archive Admins. The contributors section has some new additions too: in the course of polishing up and expanding on the guide to requesting a package removal, we discovered and split out the guides on checking both reverse dependencies and publication history. We expect the latter page in particular to grow considerably, since investigating package histories is so important.
We also created an “Archive Admin museum” page. This page contains all the content we found that no longer represents how things are done, but might be of historical interest or value to someone.
What’s up next?
To keep things varied and interesting, I like to have three phases of work going at any one time: things that are almost finished, things that are in progress, and things that are just starting.
Almost finished:
Now that the Archive Admin docs have had their overhaul, we will be able to put in redirects from the wiki page(s) to the new content. We are also going to make the Archive Admin code owners for this content so that team members are notified to review whenever changes are proposed.
In progress:
I’ll also be paying attention to the pages added to staging that still need some work – to make sure that nothing stays in staging too long, and that we keep up a good pace of moving pages into the docs. I’ve made a start on this already with the pages about germinate and phased updates.
Getting started:
I’m also going to get started on migrating the Ubuntu Maintainer’s Handbook, which has become a popular resource on packaging and Ubuntu development in recent years.
How to get involved
There are many ways to help with these efforts, and we welcome all kinds of contributions!
If there are pages you’re interested in, pages from the wiki you want us to migrate sooner rather than later, or just general suggestions that would improve your experience of using the docs, let us know on our issues list.
We also welcome technical reviews and updates on the content itself. If you spot something that isn’t quite right or could be improved, please feel free to submit a pull request with your proposed changes. Check out our contributing page for more details. The more eyes 
we have on the documentation, the better it will become!
And of course, if you’re new to contributing in general and want extra support and guidance, Robert and I are both involved in the Canonical Open Documentation Academy, where we are posting fresh issues regularly – get ‘em while they’re hot! 
Thanks in advance for your help 
Story corner
In the last post, Robert introduced the new principle by which we are organising the Ubuntu Project documentation (which I’m calling “Diatax-ish”). I wanted to give a slightly longer explanation of how this system was designed and developed.
Why was it needed?
After migrating the first wave of documentation, we noticed that the initial plan/outline wasn’t working as well as we’d hoped. The “governance/development/archive admin” split worked well for us behind the scenes in coordinating the overhaul, but it wasn’t always obvious which category things should fall into. More than that, the Diataxis top-level split was leading to content being placed together that shouldn’t have been – unless we used 3rd or 4th level drop-downs, which is not ideal when you’re trying to navigate to what you’re looking for.
If you’ve ever seen videos of a crow fitting shaped blocks into holes, it felt a bit like that.
All the processes and tasks, people and roles, as they’re documented, are like the differently shaped blocks. The initial setup had some holes that would fit some of the blocks, but most of the blocks just didn’t fit (no matter how many times we turned them over and tried them from different angles). It felt…unsatisfying. So maybe we needed to cut some differently shaped holes.
What did we really have?
Most of the content we’re migrating can be clearly categorised by Diataxis principles as either “how-to” or “explanation” – it’s either instructions on how to do something, or an explanation about that something. There’s very little “reference”, and the “tutorials” are really more like how-tos. A top-level split of only two categories seems like a missed opportunity in the navigation menu.
Then I noticed we have a natural split between who the content is for:
- People who are contributing (fixing bugs, making new packages, making requests)
- People responsible for approving contributions
There might be more than one contributor, or multiple reviewers/approvers for any particular process, but for each participant in any given process, they are either proposing something, or they have the permissions to approve that something. They might even switch between these groups from one day to the next, depending on what task they’re doing.
So what does this mean?
We commonly use Diataxis as a compass. If we examine a particular page (or our goals for the page), we can ask ourselves “does it inform the reader’s action or cognition”. In simpler terms: is it about doing something, or understanding something. So far, so good – this agrees with the conceptual split of the content we have.
Next, we ask ourselves “does it serve the reader’s application of skill or acquisition of skill”. More simply put, is the reader at study, or at work. This, then, is where we identify the root of our divergence. Every contributor can be considered to be “at work”. So what happens if instead of study/work we use a contributing/approving split? We can plot this on a compass, the same way as we do for Diataxis.
Let’s test this compass. Using the horizontal axis first, we can assess the page and decide whether it’s about doing something, or understanding something. Then we can ask whether it’s serving the user who is contributing something, or reviewing something.
Let’s take the example of a guide on how to fix a bug. If it contains steps or actions, then it must be about doing something. Fixing a bug doesn’t require any particular permissions – anyone can do it. That must be for the user who is contributing something. We’re calling this segment of the axes “contributors”.
Similarly, if we have a page about reviewing an SRU. It contains all the information a reviewer needs to be able to complete an SRU review, which means it’s about doing something. However, only an SRU member can approve an SRU – this means it’s about approving something. We’re calling this segment “maintainers” for now, since it collects together the guides for all of the special roles with elevated permissions.
We can do this exercise for every combination of the axes:
| If the page is about… | …serving a user who is… | …then it belongs to… |
|---|---|---|
| Doing | Contributing | Contributors |
| Doing | Approving | Maintainers |
| Understanding | Contributing | How Ubuntu is made |
| Understanding | Approving | Who makes Ubuntu |
If there’s ever any doubt about which segment something belongs in – because it’s equally necessary for both contributors and maintainers, it should rightly go in the contributors section. This is because it’s impossible to become a maintainer without first having become thoroughly familiar with all of the material contributors need to know. This ordering is also reflected in the fact that contributors appear at the top.
What does this give us?
So far, we’ve been able to fit all the blocks – and it’s been considerably easier to categorise and sort the pages than it was before. Our hope is that by splitting it in this way, it’s also easier for our readers to navigate to the page they’re looking for, without having to already know where to find it.
This is our first attempt at improving the navigation, and we’re keen to improve it further if we can. If you have already tried to use it, we’d love to know your thoughts. How was the experience? What do you like/dislike about it? Let us know in the comments!