These past two weeks have seen a major reorg of the content structure for Ubuntu Project docs. Sally and I have been struggling to create a meaningful organization for both the existing content and the stuff that is yet to be developed. One that would make navigation simple and finding what you need intuitive. So, Sally stepped up and prototyped a new structure that roughly corresponds to the contributor personas.
Are you wondering what all this is about? Check out our previous two blogs on the topic of Ubuntu Project docs:
Content (re)organization
The reorg proposal, which was informed by discussions with experienced maintainers (notably @jchittum, @enr0n, @lvoytek, and @paelzer), and whose tires we kicked extensively, has now been merged and can be previewed in the live documentation. It’s not set in stone, and we welcome feedback on it.
While the new organization of the content continues to observe the fundamental tenets of the Diátaxis framework, the top-level categories are now based on contributor personas – or, better put – pathways that individual types of contributors can intuitively follow.
These are the top-level categories:
- How Ubuntu is made
- Contributors
- Who makes Ubuntu
- Maintainers
If you’re interested in the logic behind the whole thing, look at the pull request that implemented the change.
Packaging Guide
I put hours into reviewing, fixing, and updating docs that were languishing in the Packaging Guide PR queue. Everything that could be brought up to snuff and merged has been merged. I then took the entirety of the PG content and slotted the individual topics into Sally’s new structure for the Project docs. This has now also been added to the repo’s staging area.
As a part of the merge, I fixed many formatting, mark-up, and language issues, and as there’s now no point in backporting all this work into the (original) PG, I’m planning to archive that docs set’s original repo (following acks from those involved in maintaining it).
Archive Administration
Sally imported the bulk of existing AA docs into the repo’s staging area and has started working on getting them into shape. The initial move consisted of converting all the wiki content into Markdown and splitting it up according to Diátaxis. Given that the AA team also has some more up-to-date content, the next thing will be to fuse the docs from the wiki with the current (but incomplete) guidance.
Miscellaneous
Aside from the “big stuff”, we have also busied ourselves with a bunch of janitorial tasks:
- Fixed and updated invalid links
- Fixed spelling (incl. changing remaining occurrences of BritEng into AmEng)
- Updated wording to have inclusive language (which included submitting an update to the
germinatetool: MP #487117) - Updated and improved Sphinx config
- Updated and extended contribution guidelines (to include CLI formatting and semantic mark-up)
Community and Open Documentation Academy
Lastly, I onboarded the project to the Canonical Open Documentation Academy and filed an initial batch of simple issues for would-be contributors to pick up. As always, all contributions are welcome, but if you happen to know of someone who might be interested in gaining a foothold as a contributor to an open-source project but doesn’t really know where they could start, point them to the Ubuntu Project ODA issues list.
What’s next?
Next steps will be mostly about getting the AA and PG docs out of staging. There’s some overlap, some stuff that needs fixing, and much that has yet to be written. But it’s great to see the ‘project docs’ project taking shape!
That’s all for today. Until next time!