Outdated Documentation

Documentation
,
1

OK, I will bite.

The most visible resource on Ubuntu is its documentation. help.ubuntu.com articles come up in any search for information on Ubuntu.

The problem with it is that the vast majority of it is completely out of date (more on this later). While the official desktop and server guides are more up-to-date, they suffer from the “middle school text book” issue. They are correct, but if you don’t already know what you are doing, utterly useless. They may cover the concepts, but they don’t teach them to the uninitiated, nor do they provide usage models that would allow non-power users to actually do useful things.

I said the vast majority of the Ubuntu documentation is out of date. Lets quantify that.

https://help.ubuntu.com/community/Servers is one of the top level help pages. Lets go through part of that page and see what version of Ubuntu each entry was written for.

Networking

  • [Basic networking] (14.04)
  • [LinkAggregation] (17.10)

** Authentication **

  • [OpenLDAP server] (12.04)
  • [LDAP client authentication] (13.10)
  • [SettingUpNISHowTo] (11.04)
  • [Active Directory Authentication] (9.10)
  • [Kerberos] (12.10)
  • [SecurePass] (10.04)

** Wireless **

  • [Wireless Access Point] (15.10)
  • [Wireless Broadcast System] (7.10)

** Web servers **

  • [Apache PHP MySQL] (10.04 with some 13.04 notes)
  • [Highly Available LAMP Server] (9.10)
  • [Ruby on Rails] (9.04)
  • [Apache Tomcat 5] (6.06)

Other top level pages are no better.

The Ubuntu Community Installation Guide has not been updated since 2018.

The Application guides since 2015

The vast majority of the hardware guide since 2018

The Printer guide since 2013 (and printing has changed a LOT!!)

The scanner guide since 2019 (and I did those edits. SANE has changed a LOT in the interm…)

Network Devices since 2012

I could go on, but the point is Ubuntu’s most visible documentation is basically a big case of document rot.

The use of business models would help a lot. See the Small Business Server documentation as an example.

Unfortunately, I don’t think this is going to be solved by a volunteer effort. While I am willing to put some volunteer time in, the documentation side needs a complete re-think.

Updating documentation is a LOT of WORK! And its not “fun” work (if it were, it would be updated).

3 Likes
2

First, thank you for biting, welcome :grinning_face_with_smiling_eyes:

‘The “middle school textbook” issue’ is a great new phrase, thank you for that.

Docs is a large many-headed beast, let me try and clarify your post and then answer what we can/might be able, to do.

Ubuntu documentation is absolutely the most visible, but it’s actually much more varied than you noted, you get help.ubuntu.com, but also wiki.ubuntu.com, askubuntu.com, and sometimes forums.ubuntu.com as well as specific documentation pages underneath ubuntu.com when you look for documentation/help.

The problem with it is that the vast majority of it is completely out of date (more on this later).

I would say this is not quite the problem, while there is documentation out there that is out of date,t he real problem is the up-to-date/maintained stuff is not visible/obvious. For example, the help.ubuntu.com page informs you that as of 2020 server docs moved to ubuntu.com/server/docs. But that’s not obvious to anyone if they find the docs elsewhere or don’t read this text.

Whether or not they suffer the “middle school text book” issue though is a separate topic :sweat_smile:

Ubuntu’s most visible documentation is basically a big case of document rot.

Your list here and investigation into its datedness is remarkable. And frankly unarguable.

Small business documentation? What do you mean? Can you provide a link? I’m finding a bunch of very dated Microsoft pages?

Finally, I agree with you, this isn’t going to be solved by volunteer effort alone, it needs a proper plan, and someone to drive it on the community front. I can also say that its a significant topic within Canonical to sort out for each project specifically, though I don’t know how much thought has been given to places like help.ubuntu.com so I’ll make sure to make that part of the discussion.

Before I start spouting ideas and proposals though I’d be interested to hear @gunnarhj and @dsmythies take on your comments. They certainly have a lot more context and experience than me in this area.

P.S I’m going to split this topic out so it can get more visibility.

1 Like
3

For my part of it, I have been mainly involved in the Ubuntu Serverguide maintenance and publication for the previous decade and until it moved to discourse as of the 20.04 release. I also try to help @gunnarhj with publication of the desktop guide. When we compile and publish help.ubuntu.com, that is only the active versions of what is under the “Official Documentation” tab on that root web page, namely the desktop help, older serverguides and older installation guides. I know nothing about the “Community Help Wiki” tab, and consider the multiple masters to be part of the problem.

As for as the desktop help and serverguide, it has pretty much been just @gunnarhj and myself for several years.

Linux in general seems to have never considered the ripple effect of required documentation updates and changes when considering the cost of changes.

4

I wasn’t ready to tackle the whole mess, but you are correct, the issue pervades all of the places you mentioned, plus here, man pages, bug tracking, mailing lists and many, many more. Being varied is not necessarily a bad thing, its the not having a propagation process and the staff to do it that is a bad thing.

When a bug is closed, it should be reviewed to see if it needs to be documented in the primary documentation, but thats not done.

When a mailing list discussion or forums discussion ends, it should be reviewed to see if it needs to be documented in the primary documentation, but thats not done.

And so on.

For example, a discussion on a mailing list or forums should lead to an entry on wiki and sometimes an article on ask. If deemed appropriate, that should then be fleshed out to a proper and official article on help. Help should then lead to server/desktop guides.

Parts of that are great community projects. Forums and wiki specifically. But other parts don’t lend themselves well to being volunteer efforts. Its not hard to get people to write a new article. its almost impossible to get volunteers to keep them updated over the long haul.

The SmallBusinessServer is at https://help.ubuntu.com/community/SmallBusinessServer. Its a set of tutorials with a specific use model in mind. When complete (and unfortunately, paid work needs to happen before I spend any more time on that project), this set of tutorials makes Ubuntu much more accessible to any anyone running a small business.

5

I am actually looking for a new job, so if you are interested, I could give you a proposal for solving this many headed beast.

Off the cuff, it would take a team of 3-5 full time documentation people to actually solve the problem in the long term, and it would take developer time to modify existing systems to make the processes actually work.

6

I’m not seeing a lot of bite-sized or entry-level documentation tasks for interested volunteers to try out. (Are they simply in a place I’m not looking?)

Do we have a way to identify those?
Are we connecting new volunteers to them?
Are new contributors getting positive feedback after their first contribution?

EDIT: Well, right after I say it, one pops up. This is the sort of thing where I’m quite happy to be wrong.

2 Likes
7

I feel this topic is too broad, also after @rhys-davies split it out from the “Community Team” one.

The Community Help Wiki indeed includes many outdated pages, and would motivate a separate topic IMO. But that wiki is a special case, and not representative of Ubuntu documentation in general. It’s simply an area where Ubuntu users have contributed over many years with tutorials and tips in order to help other users. While individuals or teams try to keep certain pages of the wiki up to date, there is currently nobody who is responsible for monitoring/maintaining the contents as a whole.

2 Likes
8

gunnarhj wrote:

While individuals or teams try to keep certain pages of the wiki up to date, there is currently nobody who is responsible for monitoring/maintaining the contents as a whole.

Yes, this is a significant part of the issue. No one is “at the wheel” driving the docs side of things. Can you imagine the development of the ubuntu operating the way docs operates?

Their currently is no system for contents to go from a bug report/forum/list/irc/whatever into the necessary documentation.

Their is no one looking at the volumes of documentation an propagating and updating/revising that in a systematic way.

All of the places where parts of the docs are created do not have the tooling in place to streamline the documentation process.

Their is no system for ensuring the documentation is updated and relevant to the whole process.

Their is little understanding of the differing classes of documentation
needed to ensure the long-term health of the whole ecosystem.

  • Concept documents intended to explain the concepts in simple ways for those new to it
  • Tutorials that walk a user though implementing a new concept.
  • Tutorials and reference materials for taking a concept a little further
  • Tutorials and scripts for actually getting a more focused system up and in place
  • Reference materials

The root of the issue comes down to the fact that there is currently nobody who is responsible for monitoring/maintaining the contents as a whole.

11

Completely agree. I’m grasping for ways to reduce the complexity, and seems like @5g3-steven-7tv has suggested one, so I’ll throw this sketch out into the middle of the room. I’m not married to this, and I can see many of the same holes in it that you will. It’s an attempt to match the classes of documentation to the current activity in that class.

  • Tutorials/Initial: I see a lot of monetized YouTube videos “How to install Ubuntu” and “How to install a scanner” in addition to the tutorials on tutorials.ubuntu.com. 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 (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.

My initial takeaway using this framework is that there is action in each class. Some of that action seems to be taking place outside of the Canonical or Ubuntu infrastructure. There seems to be some low-hanging opportunities within reach, and there are a few seemingly-intractable knots. It’s possible that wiki’s bitrot might be terribly embarrassing…but no worse than that.

I’m quite open to other ways of breaking the problem into more digestible pieces.

2 Likes
12

I think we first need an actual long-term plan, and I think we need an actual team to implement it and do the regular follow-up.

The various places where documentation happens need to have the tools to allow help documents to be created / updated.

Concept documents will rarely need to change.

help documents, tutorials and the like need to have a process to review them with every major version upgrade. help.ubuntu.com/community/10.04-10.10 should be the landing page for Ubuntu version 10.04 and 10.10. All tutorials and help pages for version 10.xx should reside under that. When its time for version 11, everything should be updated and re-verified as it is copied over to help.ubuntu.com/community/11.04-11.10.

Let me give you an example of how pervasive the rot issue is.

That tutorial points to

as the authorative reference. Except that SambaServerGuide was last updated in 2014 for Ubuntu 14.04 and SAMBA 3.6

Or have we looked at the Ubuntu Desktop for the Enterprise? Last updated in 2019, and the recent intergration with domains is HUGE to enterprise.

13

Let me catch up on the few days of posts I’ve missed:

It’s good to know and thank you very very muchly for keeping the desktop help and server guide under your wings for so long @dsmythies and @gunnarhj

@5g3-steven-7tv you’re right of course that this many-headed beast requires many heads in many team(s), and it is being addressed for the various different specific projects that Canonical touches, but I for one would love to see a proposal for how we might tackle the less but still many heads of the community side of documentation? (see last quesiton in this silly-ly long post)

I love the quick call up for a new job :sweat_smile: , this might be of interest to you if you are looking: https://canonical.com/careers/2288147/technical-writer-remote

But until Canonical gets a stronger hold on its documentation there’s unlikely to be hires to help community documentation, 3-5 full time certainly not. But stranger things have happened, we’re hoping to hire soon for people to join the community team and that could be a significant function. Once that becomes a think I expect it’ll be shared here.

@ian-weisser all great questions that need answers. We don’t have a way to identify issues besides them cropping up on discourse, the best thing would be a centralised place where these kinds of issues can be logged, maybe that’s reviving (if it’s dead? I don’t know): Ubuntu Documentation Contributors in Launchpad

and make it very clear how to log them (that’s a guide I could start but would need experienced help to perfect) I’m thinking a simple guide linked to in allt he right places that goes thorugh the proper process. And then a team of volunteers to connect them to and nurture when things happen, which could be in Launchpad too, but Launchpad is not so conducive to conversation :sweat_smile: so maybe that’s a community docs category here in discourse.

I don’t think this is too broad yet, I agree with @5g3-steven-7tv here. I like that you want to break it down into manageable chunks, and that will 1000% need to be done, but we need to land on a higher-level process that we can agree on and plan to be sustainable before we start trying to carve off in different directions. Which is then what you seem to go and do @5g3?

We’re talking about 3 problems at once and I’m getting them jumbled in my head, so, from top down its:

  • How we manage community documentation

  • Then where should that documentation live and how the pieces in that breakdown are maintained

  • Then the individual pieces of rot. Because the ‘pervasive rot issue’ you flagged there would be solved by the higher level process and wouldn’t be a rot issue as much as an issue filed to the team to be put up for contribution.

Thus, woof, sorry for the extra long post, thus, I would love to see any ideas anyone has for the kind of strucutre/processs/methods of management for communtiy documentation here in this thread, then I can happily turn them into a proper plan/proposal, we can get a group together, I can even poke that Launchpad group, have a meet (or two) and maybe get some stuff going again…?

14

You are getting them jumbled because they are all inter-related.

So, to be clear, I am NOT just talking about community documentation. I am talking about ALL documentation.

Let me outline a little of the kind of system I see as being necessary.

The technical system would be a document ticketing system to cover ALL documentation.

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. 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.

Thats a start on a high level system.

1 Like
15

Gosh, hello. I don’t typically pop by but I’ve seen enough of people struggle to try to update the documentation as a means of trying to contribute in my short time of being here so I’ll chime in. For Rhys’ sanity, I guess I’m addressing:

By adding in a little more ‘data’ on how I suspect community documentations ended up rotting, and what we could do - even if it’s a some low hanging fruit of a solution - to fix this

I actually think there are many of these sort: I think that the biggest source of bite-sized or entry level documentation tasks come from people who happen to’ve used a wiki link, and realized from their interactions that there is an outdated error.

We’ve seen people bring up errors (if they even thought to make things known on a communication platform) via askUbuntu, this discourse (myself included one time) - but most effectively the ubuntu-docs mailing list

The problem isn’t necessarily knowing what needs to be changed in itself: Their main challenge is to figure out how to edit the documentation. Which results in them having to wrangle not only the outdated user interface of Launchpad, but to gather some courage to try to join the Wiki Editors team. When I first installed Linux on my new laptop, having primarily had a background straight out of uni in closed-source, make-a-profitable-product-first,-sod-the-other-priorities, this was a really draining process - even if it wasn’t the most technically challenging. It rightfully signalled that trying to contribute to Ubuntu is currently an uphill battle for newcomers, and I should wait till I had absorbed a little more quietly.

While this might be true, I think that people who’ve contacted the ubuntu-docs mailing list had the right idea at the best place to get an documentation error known and fixed. I’m not sure if there is a need for someone to be wholly in charge, just that people who didn’t have access to fix the docs know that they could let someone know who can. Documentation fixes are on the whole, just requiring small changes here and there - the recent need to replace all freenode links to libera being a good example of that. Something like the ubuntu-wiki could be managed as a ‘whole’ mailing list at the moment.

So I had a really simple suggestion to solve this: 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?

I think that if we try to solve these little problems from the perspective of a new user, it would start to highlight what needs to be prioritized first. Ubuntu is a highly visible open source product after all, I’m sure many have thought of contributing but got overwhelmed with quite what this all entails in 2021

4 Likes
16

I would like to solve the little problems on a long-term basis.

Yes, getting people to make suggestions is absolutely necessary.

Getting things into an order that will support volunteers and staff is necessary.

but i have been around this long enough to know that we really need a comprehensive fix that is designed to take everything into account.

1 Like
17

This is something we could possibly do with a Wiki banner that would then point to a static site with exactly these directions, if not things like style guidelines, best practices, etc.

18

I want to tag @rhys-davies here since you’ve been chatting with our new Director of Documentation! @5g3-steven-7tv I want to thank you so much for all your energy and ideas, and I am hoping that having this new Director will make it easier to organize documentation efforts on the Canonical side of things, and to find ways to work together with the community to address some of the concerns you brought up, among others.

I also think it makes sense, like @HayashiEsme said, to think of steps we can take now, even with these larger goals in mind, that can not only make the documentation more updated and useful, but even help pave the way for future improvements. Because I agree that a comprehensive fix is needed, but that is going to take considerable time and coordination between Canonical employees and community volunteers. Focusing on the community side of documentation might not be that big fix you were imagining, but it will be a tremendous improvement to Ubuntu

19

I assume you replied to this part of @HayashiEsme’s comment:

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?

I’d like to remind of the fact that there is a lack of “someones”.

At the bottom of every Community Help Wiki page, you can read:

You can contribute to this wiki, see Wiki Guide for details

As regards reporting issues, for “somebody” else to fix, there is no such direction. And that’s intentional.

People still report wiki issues occationally. Sometimes they use the mailing list, sometimes they file bugs.

Ok… If a user reports a typo or broken link or something similar, I often just fix it. But more often than not it’s not that simple. Rather you need to know the topic of the page in question to be able to edit it properly.

In case of bug reports (there is no bug tracker for the Community Help Wiki, but sometimes people file wiki bugs against the ubuntu-docs package) I have used this standard reply a few times:

Please note that the page in question is a wiki page which anybody can edit - including you. :wink:
WikiGuide - Community Help Wiki
Since you seem to know how it should be changed, it would be great if you could fix it.

If you are not already a member of the ~ubuntu-wiki-editors team:
When applying to join, please also contact the team admins referencing this bug number and how you plan on improving the wiki page and they will review your request to add you to the team.

Due to the nature of the community help wiki, you can’t request changes to it in the form of bug reports.

So: If you seriously consider to turn the Community Help Wiki into an officially maintained set of documentation, then you need to first make sure that the resources are in place to deal with the consequences.

1 Like
20

Thanks @madhens for continuing the discussion of what can be done in the meantime, and @gunnarhj for elaborating on what I (unintentionally) simplified when I said

Like Gunnar said, to truly maintain good documentation, we probably should have an experienced person really should be maintaining these docs. Really, I meant to only suggest reducing the barriers to entry for small fixes as a way to revitalize the community. If people realized their small fixes made a big difference, then maybe we’ll see people more familiar with various subject matters be will to ‘maintain’ certain wiki pages.

I wrote that quote having personally felt that the root cause behind an undermainted wiki is the dwindling community numbers - in spite of the good numbers of people try to learn to contribute by first trying to fix something with the wiki (5g3-steven-7tv, who started this thread, being a clear example) - but I hadn’t meant to remove the need to remember the manpower requirements in the long term

On to discussing how contribute guidance is being communicated at the moment (i.e: continuing the discussion on solutions to encourage fixes in the meantime):

I can see why it was left vague: likely this was cause there were many people at the time who had different skills and knowledge in maintaining various docs, and now we don’t. There’s a lot of knowledge required is even navigating through the years of valuable information and sharing. In the meantime it would perhaps be nice to point them to our new Director of Documentation (grats Rhys!) or Community Representative. It is their role to ensure that grassroots initiatives can be revitalized after all - even if this is just a temporary stopgap while the community gets rebooted.

In the long term, the docs probably should stay a community initiative and not be officially maintained. That being said, I am also open to the community wiki being deleted and started all over - if people don’t feel like the wiki is a good place to build community anymore.

Gunnar I remember you mentioning when I applied to the Docs team that you and Doug struggled with people making rogue edits as a big problem. A lead maintainer is definitely key in the long term.

The underlying issues behind why the wiki is undermaintained is a big problem, with many root causes: community being one of them. I guess I’m also saying in spite of discussing Community Wiki improvements that I am in reality not fussed how if the wiki’s problems are even solved by lowering the barrier to entry for small fixes – just that the root causes stop happening. Which is not an easy thing to do, at all. But I did have a little idea and a direction I figured I’d suggest if it would help motivate some change.

21

Thanks for your comment!

I like the wiki concept, i.e. “anybody” being able to add or edit pages.

Gunnar I remember you mentioning when I applied to the Docs team that you and Doug struggled with people making rogue edits as a big problem.

The background is that a few years ago all you needed for edit access to the wikis was a Launchpad account. But bad guys, who submitted spam or even deliberately sabotaged, entered the scene, so the barrier had to be raised and the ~ubuntu-wiki-editors team was created.

But the barrier is still not very high IMO. Creating a Launchpad account and joining a team aren’t much of hurdles for an Ubuntu user who is motivated to help out.

Let me explain what I mean when using the term “officially maintained”: I’m not talking about Canonical vs. community — official documentation may well be community maintained. No, I’m talking about documentation where you provide a bug/issue tracker or otherwise encourage users to point out errors, ask for improvements etc… By doing so you create expectations that somebody is there to address the issues, which in case of the wikis would be bad as long as no such body exists.

And it’s really not what the wiki concept is about. Instead the idea is that anybody with sufficient knowledge is welcome to contribute directly.

With that said there are two problems with the wikis:

  1. The wiki software needs to be replaced.

  2. We need to figure out a model so outdated pages get deleted sooner or later.

But those items deserve their own topics.

1 Like
22

I think the real question is:

What is the future of Ubuntu documentation?

To answer that question, Ubuntu needs to have an idea of what they want out of the documentation (the benefits) and what they are willing to spend.

Onboarding new users?
Onboarding existing users to new tech?
Supporting new users?
Supporting experienced users?
Supporting use cases and developing those markets?
Tinkerers?
Developers?
Selling services?
Is it to try and build “community”, and if so, by what definition?

What does Ubuntu want from having documentation?