July 27, 2021

Ubuntu Documentation Issues

Over the lifetime of the Ubuntu project documentation has been written by thousands of people. From technical specifications, to meeting minutes, to translations in dozens of languages. But with such extensive contribution it has become fragmented, disjointed, and confusing to parse, even for the most diligent community members. I’m here to give the state of things, tell you where everything is, and proffer my opinion as to how it might be turned back into the shining light it could be. Spoiler alert, it’s a slog.

Photo by Sigmund on Unsplash

Context

Recently I’ve been having conversations about how much of a pain in the ass Ubuntu documentation is. Not that it’s bad, necessarily, but that it’s a mess. It’s hard to contribute to, it's confusing because there’s numerous places for the same thing, and a lot of what exists is out of date, unmaintained, or inaccurate. Really the three things documentation should absolutely not be.

But, there are loads of community members who are interested and who really care about Ubuntu documentation. It’s the most obvious thing for new users and new contributors to look at, it should be one of the easiest things to contribute to, and should represent both the project itself and, to an extent, the community behind it. At the moment this is not that case. It’s a mess.

It could be worse, there are some really wonderful people who, entirely of their own volition, keep the documentation away from the grave. Which I should stress is crucial, it's easy to think that well, if it died, we could resurrect it. But that would not be the case. Should the documentation die, it would be the effective death of an enormous part of the community. Not only would it be a huge blemish on the project but would be telling the community that cares about it that their contributions aren’t a priority.

The problem is, it’s seen as a huge undertaking and who would even handle something like that?

Photo by Felix Tchverkin on Unsplash

The state of things

When we talk about ‘Ubuntu documentation’ we could be talking about several different things. There are perhaps three most prominent places, wiki.ubuntu.com, help.ubuntu.com and discourse.ubuntu.com, which feed the ‘official’ documentation for Canonical at ubuntu.com. But you also have things like docs.ubuntu.com, ubuntu.com/tutorials, ubuntutor.com and places like askubuntu.com and forums.ubuntu.com where docs don’t officially live but where there are hordes of documentation-adjacent information.

Each of these places has sub-domains or sub-pages with varying degrees of accuracy, maintenance, and structure. Some link to each other as official sources, others don’t link anywhere, and some are contradictory without clarity on which is most reliable. The maintenance structure/methodology is unclear and contributing to documentation as a community member is difficult.

Now, Ubuntu is still a very successful project, this wouldn’t be the case if you couldn’t find reliable information. This comes down to two factors, the pillars on which Ubuntu documentation currently stands; core contributing members of the community with the permissions and the inclination to make a difference. And Canonical’s contributions through the projects and products that they work on. The core members keep the lights on in all the aforementioned places, and Canonical maintains the documentation that is most in their focus on discourse.ubuntu.com.

For the rest of this article when I refer to documentation I mean ‘community documentation’ - that’s everything bar the ‘product documentation’ that is maintained by paid engineering teams at Canonical.

Photo by Dylan Gillis on Unsplash

Problems

The problems here are not unique, they’re not special cases that have sprung from the Ubuntu ecosystem, they are common problems that have been addressed and solved by different communities and organisations in numerous different contexts. It boils down to:

  • Outdated documentation
  • Visibility/discoverability
  • A lack of a system/process for documentation maintenance and contribution
  • No one is responsible for monitoring and maintaining docs content
  • Accessibility for community members
  • Dog shit Wiki performance

Most of these issues are pretty self explanatory. I’ve taken some from my own experience, some from a wonderful discussion about outdated documentation, and some from Alan Pope’s (long term community member and contributor) blog post about fixing the ubuntu wiki. If you want to dig more into the issues themselves those are good places to look. Or open a thread on discourse and I’ll be happy to get into it more.

Naturally, there’s a lot of overlap, and it’s very easy to say that you can’t do one without doing the other and end up in an unproductive circle. And this in itself is another problem, there’s so much that needs doing, where do we start? Well ...

Solutions

Lots of people have ideas. Lots of people even have good ideas, but ideas are a dime a dozen, what really matters is execution. Which in a context as broad as this means we need a driving force. Leadership, to operationalise the problem. Whether that’s a team or a committee or an individual, it doesn’t matter, something or someone needs to take the reins.

After that they just have to battle a dragon solve the problems. Can it be done? Absolutely. There are lots of people in the community who I’m certain would get involved and I’m sure if it was done right new people would take notice and join in. The other elephant in the room is Canonical, but I’m also certain that if there was serious interest from the community, an individual or a group, with a plan, we (the community team) could make it happen. In a company as relatively small as Canonical priorities have to be set based heavily on ROI. If we could put together a plan that makes the value obvious, we could do it.

The question is, is there anyone out there who could lead it, who care enough, and has the time to put the effort in. I can help, but I can’t lead this one at the moment.


Anyway, we had a good ol’ discussion about this over on the Ubuntu discourse and I spun that discussion out into a call for ideas while we work on finding a leader. Spoiler alert, I’m going to start by trying to convince Canonical’s director of documentation to do it. Out of that initial discussion came some really interesting ideas that I wanted to highlight here. None of these are mine, but I like 'em. Hopefully more ideas will come.

Splitting docs into classes

  • Tutorials/Initial: I see a lot of monetised YouTube videos “How to install Ubuntu” and “How to install a scanner” in addition to the tutorials on tutorials.ubuntu.com 1. I wonder if we can offer guidance to some of those video-makers to fill gaps - that might be a bite-sized volunteer task.
  • How To/Checklist: I see a lot of these on 1) tutorials.ubuntu.com 1 (sometimes mis-labeled “tutorials”) and 2) AskUbuntu, in addition to the fabulous 3) Desktop Guide and 4) Server Guide. I wonder if we can break down some of those silos.
  • Discussion/Explanation: This used to be where the wiki stood out. A lot of this moved to developer blog posts. I wonder if we can draw many of those posts to Discourse’s wiki/threaded format, where volunteers can tickle the thread owners for an update-and re-post on a schedule.
  • Reference: Much of what I see has moved to reference-specific platforms like readthedocs. If developers are happy with it there, then I don’t see a need to re-invent it.

A System

The system would take inputs from any other system - bugzilla, askubuntu, help.u wiki.u, wordpress, the man page viewer, support ticketing system, launchpad, github, and any other place where documentation exists, questions are asked or ubuntu content exists or is created (yes, this means we would need plugins for major content creation systems).

Tickets would collet a little basic data - url, date, reporter, ubuntu version, other software used (and versions) and a note about what the documentation or problem is.

The ticket is then reviewed by an editor, where the ticket is assigned a team, a support level, a difficulty level, a likelihood level and a severity.

Those tickets are then picked up by various team members (including both paid staff and volunteer staff depending on the team or teams it is assigned to)

Teams are fairly obvious.

Document levels refer to the supported status of a document. Level 1 documents are considered unsupported documents. On the public side, these are very appropriate for brand new volunteer editors and would appear on a site like wiki.ubuntu.com 1. On the internal side, they may be a shared note for support staff.

When a level one document is ready (or another pressing need for that document comes up), it gets promoted to level 2. At this stage, it is reviewed by a mid level editor, cleaned up and fleshed out. For internal documents, this may be taking a support note and giving a basic methodology of fixing a problem.

Level 2 docs get promoted to level 3, or minimally supported documents. For public documents, these may get promoted to help.ubuntu.com.

Level 3 docs are fully supported documents. They may have a technical team already assigned to them. The public documents are supported by staff, and are updated for every version of ubuntu.

Level 4 docs are the official docs (e.g. server guide and desktop guide).

Level 5 docs are for paid subscribers and are fully supported by paid staff.

Docs should have tabs. The official published version, the current working version, and the suggested edits tab.

Likelihood and severity are ratings on how common the issue is and how bad it is when it happens. These scores allow for prioritizing documentation issues.

Difficulty is a rating of how difficult the editor thinks the job is. 1’s may be simple spelling and grammar errors, where level 5 is a complete rewrite of a major documents. This is used to help assign volunteers and staff appropriately.”

Quick fix for users

Could we just have a little, fairly visible sign on the Ubuntu-Wiki that people with amendments should either feel free to apply to join the Wiki Editors group - or to direct them to the mailing list (or potentially even the discourse) to let someone know to edit it?

Canonical and Community roles

I would break that down farther: Both Canonical and the Ubuntu Community have different roles, and are likely to have different goals.

Example: Community does not sell services, and has historically handled new-user support.

I think community-maintained documentation should reflect both the strengths of Ubuntu and the goals of the Ubuntu Community.

  • Strengths of Ubuntu: I think folks choose Ubuntu because of its reputation for friendliness to new users, ease to use (discoverable), built-in security, reliable stability, sane defaults, and broad software compatibility.
  • Goals of the Ubuntu Community: I think the community provides a sense of fellowship, a starting point for direct contribution to Ubuntu, and a starting point for more complex learning about Linux and Free Software.

So, with those in mind, I think what we want out of community-maintained documentation should include:

  • Successful new-user onboarding
  • Help users transition to new tech, new services, and new releases
  • Supporting defined use cases
  • Supplement upstream documentation. Address conflicts with upstream documentation (Example: How to install Wine, and how to undo the damage if you followed the upstream Wine instructions already)
  • Encourage users to become participants and contributors.

Of course, many of these can also be lumped together as "Answer frequent support questions (both new and experienced users)

Conclusion

The community documentation needs a champion, or a team of champions, to kick it into gear. It seems unlikely that someone inside Canonical will do it because they have their own docs and not a lot of time. The community team can’t do it alone because it’s a many headed beast and we have other beast at the moment. But of course if you think this should take priority over more personable activities, office hours, outreach, and getting Canonical to work more openly, let us know, and we’ll adjust.