In this post, I will focus on two broad questions:
- How will the new Ubuntu wiki relate to our other content platforms?
- What type of information will the new wiki contain?
Posts in the Ubuntu wiki project series
Our platform ecosystem
When I talk about âplatformsâ, Iâm referring to several digital spaces where we exchange information and content about Ubuntu.
Three that come to mind are Read the Docs, Discourse, and Matrix.
So the question is:
What is the role of the Ubuntu wiki among these other platforms?
Here is the most concise description I can think of for each platform, focusing on how we generally use them today:
- Read the Docs is where we host most of our official technical documentation
- Discourse is where we host community discussions and periodic content
- Matrix is where we host real-time communications
What is periodic content?
Content shared at regular intervals as an ongoing series. Think newsletters, team updates, and meeting minutes.
I donât think there is any potential confusion between the role of the wiki and Matrix, so I wonât consider it further here.
If you work at Canonical, you might also be wondering about the Canonical Library. Simply put, the library is for internal documentation relevant to Canonical employees. The new Ubuntu wiki is a community project, and is not for internal documentation. They are different projects with different goals.
Comparing platforms
The wiki is open, additive, frictionless
The wiki is a place for information of general interest to the Ubuntu community. It is characteristically low-friction, enabling both technical and non-technical users to collaborate on information about Ubuntu that the community will find useful. This is why I previously emphasized wiki features like the visual editor, which will make it easier to attract a broader range of contributors.
Unlike official documentation, the wiki is not gated by an engineering team and does not require sophisticated knowledge of tools and workflows to make a legitimate contribution. Unlike a forum, its purpose is not to generate discussions but rather to produce, mature, and connect information.
Aside from general standards of decency and relevance, the wiki does not place significant constraints on subject matter. Pages can be:
- Provisional or mature
- Technical or non-technical
- Niche or broad
- Focused on Ubuntu but also third-party software for Ubuntu
- About apps, tools, and customizations that are supported or unsupported
This characteristic looseness means that wikis can get messy without some community governance. But wikis also create openings for the quick expression of new ideas and connections. Like a Digital Garden, it is necessary to let the information grow organically, with some occasional pruning so that things donât get out of control. A productive âbalance of chaos and cultivationâ.
Without a place like a wiki, there is a risk that some information that could be useful for the Ubuntu community simply never gets collected. An unrealized contribution is more hidden than a bad contribution, or a contribution that has gone stale, but itâs just as much of a problem.
Documentation is promissory, robust, standardized
When we publish documentation, it is a promise to the user that following the documentation is a reliable way to achieve their goals. If the documentation fails in that respect, it is a problem, and the team that owns the documentation has an obligation to fix it.
For something to be included in our documentation, it is not sufficient for it to be merely interesting or relevant. It must help a broad set of users achieve their goals. The documentation also has to be maintainable, so that we can ensure that it provides reliable guidance over time.
Because we want our documentation to be excellent, most teams have a dedicated technical author, who drives documentation quality standards within the team. The engineers who are developing the software also treat documentation as a fundamental aspect of their engineering work.
Making a contribution to the official documentation has certain prerequisites, at a minimum:
- Knowledge of git and GitHub
- Knowledge of Diataxis
- Knowledge of ReStructured text or an extended form of markdown
- Familiarity with the workflow (forking, pushing, pull requests, code reviews, CI pipelines, merge conflicts)
This makes contributing to our docs an experience that has definite friction, but that friction is useful in helping ensure that the documentation is high quality. Everyone is welcome to contribute, of course, but there are hurdles.
This friction is not just about us â experts who glide elegantly over the hurdles â and them â non-experts who awkwardly knock the hurdles over like dominoes. I personally use all of these tools every day. Yet, when I come back after a holiday, itâs absolutely not just like riding a bike, and more like operating some exotic machinery that gives me random jolts and shocks. It slows me down, I get careful, and, usually, thatâs a good thing.
The forum is discursive, ephemeral, reputational
As a platform, Discourse is centered around discussions. Typically, an individual, or a representative, creates a topic in the anticipation that it prompts discussion and reaction.
A Discourse post might be considered âsuccessfulâ insofar as it gets a satisfactory response, even if that post doesnât âlive onâ as durable information that we return to in the future. Think of the kinds of thing that appear regularly on Discourse:
- A blog that provokes a debate
- An announcement that attracts enthusiasm
- A question that gets a set of answers
- An event that attracts some attendees
Someone has to step forward and put their (user)name on a post. In doing so, they open themselves up to a collective discussion. The ensuing discussion is just as important as whatever instigated the discussion. The discussions have important side-effects that live outside the text, in the consensus that forms, in the strategies that teams adopt, or in the goodwill that develops. An individual can develop a reputation through their posts, questions, and answers, which is quite different from the relative anonymity of wikis and documentation.
Summary table
Hereâs a general summary of what Iâve said so far about our platforms:
| Platform | Example roles | Some prerequisites | Content types | Authorship |
|---|---|---|---|---|
| Community Wiki | Enables quick, frictionless, and emergent collaboration. Allows sharing of information that is not officially supported. |
A willingness to edit and be edited. Interest and curiosity. |
Any information of interest to the community that isnât duplicated elsewhere. | A broad collective of community contributors. |
| Official Documentation | Provides users with guidance that they need for success. Covers common and commercial use-cases. |
Knowledge of the workflow for technical contributors and our documentation standards. | Documentation that must be maintained to support users. Tutorials, how-tos, explanations, references |
Engineering teams with community contributions. |
| Discussion Forum | Stimulating discussion. Providing updates. Organizing events. |
Account registration, willingness to discuss. | Prompts for discussion and periodic content. | Individuals and representatives engaging with the community. |
Scoping the content of the Ubuntu wiki
Today, we are well stocked with high quality, official Ubuntu documentation. There is documentation for Desktop, Server, WSL, public cloud, and more. There is also documentation for specific Ubuntu users. The excellent new Ubuntu for developers documentation can help you set up a development environment on Ubuntu in your favorite language. Also new is the fantastic Ubuntu Project documentation, a treasure trove of documentation for those interested in contributing to the development of Ubuntu itself.
What then remains for an Ubuntu wiki? Below is a non-exhaustive list of possibilities:
- Third party software: that Ubuntu works well with third-party software is really important. While it is not feasible to maintain documentation on every third-party integration that is meaningful to users, this can be accommodated in the wiki.
- Alternatives to the standard: Ubuntu provides first-class support for debs and snaps. We maintain snap and have a responsibility to document it. It is possible to install software by other means, including flatpaks, and users do this. We cannot take responsibility for documenting the use of flatpaks, appimages, and others, but there is no reason why we canât in the wiki.
- Desktop customizations: one of the joys of Linux is the freedom it allows for customizing your experience. Ubuntu is an opinionated distro, with strong defaults. That does not mean it canât be customized with, for example, different window managers and app launchers. There is a large diversity of niche possibilities, perfect information for a wiki.
- Non-technical content: our official documentation is for helping users get things done but not all information is like that. What was Bug#1 and when was it closed? Why was the theme for Warty Warthog brown? This is descriptive information about Ubuntu that is a part of the history and identity of Ubuntu. It doesnât help us solve problems, but it can enrich our shared experience and understanding.
- Integrative topics: some concepts are relevant to multiple âUbuntusâ: Desktop, Server, WSL, and others. However, itâs difficult to cleanly capture that information in their individual documentation sets without duplication or fragmentation. A wiki is an excellent place for integrating this kind of information.
- Domain-specific content: users sometimes approach our software with a focus on a specific domain. For example: gaming, architectural design, scientific research, computer education, and system administration. The list is endless. The wiki can have these categories, and even cross-domain categories, e.g., Ubuntu server administration for scientific research, gaming on Ubuntu for architects who shoot drone footage (maybe not that oneâŠ).
- Hardware and drivers: an exhaustive account of supported hardware is difficult for any one team to test and document. Crowd-sourcing this kind of information in a wiki is far more realistic.
Later in this post, I include some specific content examples to get us all thinking.
Interplay between platforms
Iâve spent much of this post differentiating the wiki from the other platforms. Itâs important to say, however, that even though they are different, they can work together. In this section, I include scenarios where there might be a healthy interplay between the wiki and the documentation.
Wiki as outlet for unmaintainable documentation
When Iâm working with my engineering teams, itâs common that we discuss potential new documentation and decide to not include it. Other times, we review some existing documentation and decide to remove it. Something may not âfitâ in our documentation for a variety of reasons:
- It concerns third-party software
- It would be impractical to maintain
- It would be too niche
- It would spans multiple pieces of software
- It would not help our users solve problems
Instead of these ideas going in the trash, they could be developed and maintained in the wiki. In this sense, the wiki becomes a part of our documentation discussions, as a potential outlet.
Wiki as generator of novel documentation
What if someone puts something in the wiki that should be in the official documentation. Disaster! Donât worry, it will be OK.
As I mentioned in the previous post, each wiki page will have an associated discussion. This isnât a general discussion, like what we have on Discourse, itâs a specific discussion about that wiki page.
Someone from the engineering team could create a discussion about adapting the page for the official documentation. If the information gets adapted, then the wiki page can be updated to include a brief overview and a link to the official documentation.
In this way, new content generated in the low-friction context of the wiki could be adapted and developed for use in documentation, when it may never have emerged otherwise.
Dynamic exchanges of information between platforms
Itâs not about one place â the docs or the wiki â being âbetterâ than the other. Itâs about trying to find the place that is best for the development and maintenance of specific content.
We continuously grow new content, maintain mature content, and prune older- or lower-quality content. A wiki is just another tool to help us manage that process.
The new wiki has a more refined purpose
Information accumulated at wiki.ubuntu.com for over 20 years.
During that time, Ubuntu and Canonical evolved. The internet changed. Platforms came and went. Documentation, libraries, and fora emerged that were separate from the wiki.
The wiki served a variety of functions, including but not limited to:
- Internal docs
- Internal processes
- User docs
- Packaging docs
- Meeting minutes
- Personal notes
- Newsletters
- Release notes
In addition to the two public Ubuntu wikis, there was a third, internal Canonical wiki, which served additional functions.
This creates significant historical baggage for the wiki project. If someone associates the term âwikiâ with a specific function, they may find the concept of a new wiki entirely pointless.
- âA new wiki?! Donât we have the Canonical library now?â â the new wiki is not for internal documentation
- âA new wiki?! Donât we have the Ubuntu Project docs now?â â the new wiki is not limited to information about developing Ubuntu
- âA new wiki?! Donât we have Discourse?â â the new wiki is not a discussion forum
The old wiki used to be a vast assemblage of official docs, internal docs, and a community wiki. Now, it just needs to be a good community wiki.
Example content for a new wiki
The problem with examples is that they can limit our thinking. As you read my examples, I encourage you to think of your own.
Installing Flatpaks on Ubuntu Desktop
The supported way to install software on Ubuntu is using debs and Snaps. These are the methods that are described in the official documentation.
Of course, people donât only install debs and Snaps on Ubuntu. They install AppImages, Flatpaks, and other formats. Users donât have to do whatâs supported, even if itâs recommended that they do so. You can install Flatpaks if you want. I do it sometimes.
Itâs not feasible for us to officially document what we donât officially support. Yet, there are legitimate reasons why users would seek that information. The wiki is an appropriate place to maintain solid guides on installing software using these alternative methods.
Remote development in WSL with multiple IDEs
One of my jobs is maintaining the documentation for Ubuntu on WSL. In the context of WSL, âremote developmentâ typically means accessing an Ubuntu environment running in WSL from an editor running on the host Windows machine.
Currently, we document this remote development workflow for Visual Studio Code. I am very tempted to document similar workflows for other IDEs/editors, like Zed and IntelliJ. However, this would then require us to maintain documentation that relates to at least four applications that we do not control.
As a user of WSL, and a user of multiple IDEs, I would like to read about different remote development setups in one place. But as a technical author, I know that our official documentation is probably not the right place. In the wiki, this kind of information could be maintained by people who use the specific tools in question.
Ubuntu platform reference
What do you think of when I say âUbuntuâ? For many users, itâs probably âdesktopâ. If you have a homelab, you might think âserverâ. If youâre a Windows user, it could be âWSLâ. And so on.
Ubuntu targets many different platforms (my terminology). It runs on Linux desktops, Windows subsystems, cloud deployments, and so on.
It would be nice to summarize all of this in one place, right? Letâs say Iâm the maintainer of the Ubuntu Server docs, do I put it there? How about the Ubuntu Pro docs? The truth is that this kind of broad, integrative information doesnât particularly belong in any one of these places.
The wiki, on the other hand, is a place where such a table could be maintained, with appropriate links out to the official documentation.
The audio stack on Ubuntu
I make electronic music as a hobby. When I first transitioned to Ubuntu from Windows, I found myself grappling with strange new terminology: âALSAâ, âPulseAudioâ, âPipeWireâ. On a forum, I was told that I âneeded to use Jackâ.
I would make some music on a Sunday night. On Monday, my weekend misadventures meant audio was no longer working in video meetings. I would go back to a forum and another person would say âjust install Ubuntu Studio if your focus is making musicâ, but it wasnât a focus, it was just a hobby.
That is all to say: the story of audio on Linux is complex. There is an interesting history to some of its developments, which is probably not necessary to include in official Ubuntu documentation. In fact, it could be a distraction.
For the audio gurus, noobs, and purists, a wiki page could be perfect.
Bug #1
Somehow, I only recently heard about Bug #1. If you havenât heard about it, it was covered in the media.
Bug #1 was filed in 2004 and it is a unique part of the history of Ubuntu. The decision to close the bug in 2013 is an important marker of Ubuntuâs development and trajectory.
This is an example of interesting, non-technical information that warrants preservation, but clearly does not fit in technical documentation.
A page for Bug #1 exists in the old wiki. It was last updated in 2012, a year before the bug was closed. The page largely reproduces the text of the original bug. In the new wiki, I would like to see that page updated to include reference to its closure, the context of that closure, the media attention it attracted, and how the story relates to Ubuntu today.
Conclusion
Our challenge in developing a good Ubuntu wiki is different to that facing Arch, for example.
For one, Ubuntu has official documentation that is not in wiki form. Our wiki must then co-exist fruitfully with that documentation.
In this post, I have outlined ways of distinguishing the wiki from our official documentation. I also suggested examples of information that may fit really well in the wiki.
The next post will be shorter 
and will discuss how we are approaching archiving the old wikis.
Is there a kind of information that you would love to see in our new wiki? Do you have a strong objection to one of my diagrams?? I would be happy to discuss these ideas with you.
Acknowledgements
Special thanks to @avgomes for providing extensive feedback on this post. Thanks also to @rkratky, @degville, @sally-makin, @annecyh, @marek-suchanek, @jibel, @danieleprocida, @ecoldi, @juanruitina, and others, for various chats and discussions that helped shape the ideas therein. Thanks also to contributors through the Open Documentation Academy, for writing early version of pages that will appear in the new wiki, namely davidekete, network-charles, and eeickmeyer.
