Bringing together 20 years of documentation

In early April, jnsgruk announced plans to revitalize the Ubuntu Project documentation. The documentation about how Ubuntu is built and how to contribute, as it currently exists, can be a bit difficult to navigate. Some of it is on the Ubuntu wiki. Some is in Discourse. Some of the larger documentation sets, like the SRU documentation and the Ubuntu Packaging Guide, have been moved to Read the Docs (but separately).

In some cases, the information exists only in peoples’ heads.

To address this, over the next 6 months, we’ll be pulling together all the existing (and non-existing!) threads into a single place. Our hope is that by streamlining the documentation and updating it, we can make it easier to find the information you need, so that contributing to Ubuntu feels more straightforward, efficient and satisfying. Having a single portal, with one method of contribution, should also make it easier to keep it up to date.

The Ubuntu Project docs

The Ubuntu Project documentation will be consolidated into the Ubuntu Project Docs repository on GitHub. The documentation already has a skeleton outline and can be viewed on the corresponding Read the Docs project (which will receive an updated URL once it has content filling the outline!). The project home on RTD is also public and can be used to check on the status of documentation builds.

These efforts will be guided and supported by two of the Ubuntu technical authors: rkratky and s-makin (me!).

Where information is duplicated, we’ll merge it. Where it’s no longer needed, we’ll deprecate it. Where it’s needed but out of date, we’ll update it. And where necessary, we’ll harvest what’s in peoples’ heads :brain: (like documentation zombies?), and make sure it’s written down!

We will be giving fortnightly updates on the progress of the project over the next 6 months in this thread, so keep an eye out for those!

How to get involved

There are many ways to help with these efforts, and we welcome all kinds of contributions!

For this post, as we’re just starting to get things organized, we just wanted to introduce ourselves. Pretty soon, though, we’ll be posting issues on our GitHub issues list as well as via the Canonical Open Documentation Academy, who have been a massive help to the Ubuntu Server documentation over the past few months. These issues should be reasonably scoped and self-contained, and we’ll be talking about them in our upcoming regular digests in case any of them spark your interest.

As things get underway and more of the content gets migrated, having as many eyes :eyes: as possible on the new docs will help us to catch outdated or incorrect information we might otherwise miss.

  • If you spot something you know is wrong, please feel free to either open an issue to report it, or submit a correction. Check out our contributing page for more details.

  • If you see a question you know the answer to, leave the answer in a comment!

Thanks in advance for your help :slight_smile:

What kind of treasures await us?

Some of the pages on the Ubuntu wiki are from the very early days of Ubuntu development, and diving into the rabbit holes (or…spelunking in the caverns) can take you to some surprising discoveries.

One little gem :gem: that I discovered via the very first page I looked at was the Contributor Console, which was created to help Ubuntu contributors to make code changes 13 years ago. Apart from looking like quite a nifty utility, this wiki page also has some beautifully hand-drawn illustrations of the console screens to accompany the documentation.

When I asked around, no one had heard of it before. Do you remember it? Do you miss it? Let us know!

10 Likes

Here might be the author. Ships passing in the night. Might I suggest that you build a concordance map of every word in the constellation of 20 years of documents. Including forums and other “sunset” forums such as ubuntuforums. And Wayback Machine. That would be interesting. Context vector database. Then let AI Agents loose on the corpus concordance.

1 Like