Outdated Documentation

Documentation
,
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?

23

Here’s one take on it…

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)

2 Likes
24 
[quote="HayashiEsme, post:20, topic:22726, full:true"]

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
[/quote]

I think we need to understand that there is a lack of these people. Documentation is hard. Far fewer people have expertise in documentation, especially of this kind, than we have programers to write the code. My credentials in writing include over 2,000 published articles ranging from news stories to white papers to journal articles, and that doesn’t include things like expert reports or the more than 17 books I have written.

You can’t expect anomalies like me to step in and put the brainpower in that this needs over a consistent and long term basis, but what we need is exactly that.

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):

[quote="HayashiEsme, post:20, topic:22726, full:true"] 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.

[/quote]

Can we get Rhys on this thread?

I think Gunnar is right. If the community documentation is to go forward, it should be officially maintained. That doesn’t mean it can’t also be a community project, but we have to recognize that big parts of maintaining this is beyond what can or should be expected of a community project.

Proper staff support can greatly build a community and amplify volunteer efforts, but so much of what is needed is just far bigger than a weekend project for a volunteer. Many of the things needed to be done to fix the doc rot issues are equivalent time, energy and brainpower to developing a new program for inclusion in the main repositories. And we currently have no earthly way of breaking it up into manageable pieces.

A properly staffed project could have major pieces planned out by a staff member, then recruit people for bite sized projects that can then be reassembled by the staff into the big documentation we need. But that’s not “fun” work, you are unlikely going to get volunteers to do that work, and if you did, they would burn out really fast.

A properly staffed doc team would do the updates that are too tedious to get volunteers for. A properly staffed doc project would encourage people to contribute, as it wouldn’t feel like such a desolate place.

2 Likes
25

Yes o/ It’s a big ol’ thread and I’m enjoying the discussion :sweat_smile: I am very sorry for the delay I was afk last week on a wee holiday and I’ve been wrestling to put a blog post together covering all of my thoughts on this.

FYI since I think there was a miscommunication, I am not the new Director of Docs, that’s the lovely @danieleprocida. Daniele, I don’t recommend diving into this thread until you’re properly up to speed and rolling. We can talk it all through whenever you like.

To everyone else, Daniele is going to be the brainpower and leader behind Canonical’s docs problem, and hopefully a part of the solution to the communities docs problem too.

Moving on, I like all of this, I think we’ve identified the majority of the issues and have some good ideas for solutions. And agree with the direction we’re going in; needing a driving force and direction.

How’s about this, @gunnarhj and or @ian-weisser could you advise as to the best way to get in contact, or at least try and get the attention of people who used to work on documentation, so we can tell them we’re thinking of getting the band back together? And everyone else, let’s start another thread and create a granular wishlist of things that need, should or that you’d like to see, get done.

For example, I really like @HayashiEsme’s suggestion of putting a signpost on the wiki to point people to the right places to edit/contribute and I could break down @5g3-steven-7tv’s system into a number of suggested tasks. Here, I’ll start: :blush: Ways to improve documentation - #2 by rhys-davies

1 Like
26

I can think of two ways:

As mentioned here there is a link at the bottom of each Community Help Wiki page.

1 Like
27

In my view, the two problems are really one problem, and this problem needs a high level fix.

1 Like
28

I am trying to maintain a few sub-pages at help.ubuntu.com and one sub-page at wiki.ubuntu.com. So I am interested in your discussion. I have no ambition to work outside my current scope, but I am willing to listen to advice and try to improve what I can improve (including to delete what is outdated or confusing).

5 Likes
29

Thanks so much for posting your comments, and for your contributions!

When you maintain those pages, is there anything that makes it difficult? Is there anything that could make maintaining them easier? We want to get more feedback from our contributors and use it to improve our processes, and this is definitely an important way to contribute to the discussion!

1 Like
30

@madhens,

  • Some years ago there were log in problems, but nowadays it works well.

  • After sending an update of page, it can take a long time, tens of minutes, before it gets updated. When I look at the raw code, it is updated, but it seems to be migrating slowly to the GUI implementation. This problem has appeared recently, I think maybe one year ago. Maybe the server is not powerful enough for the amount of data at help.ubuntu.com.

  • Recently, there is also a lower limit of the size of attached files. I mention it, but I can understand why. It has forced me to learn and use github, so I need not complain about it.

  • I understand the syntax well enough to manage the pages that I look after.

  • I think someone should proof-read my pages, and give feedback. This is important! Maybe we can arrange that a couple or a few persons cooperate to maintain a set of pages (or at least that some people can regularly proof-read pages for other contributors).

    I am not a native English speaker, and I have a long experience of programming. I do not always explain in a way that helps a beginner to understand.

    Some of ‘my’ pages are probably deprecated, and I need a second opinion to decide if they should be kept and updated, or deleted.

3 Likes
31

I’ll volunteer.

I am a native English speaker. Having seen your many posts on Ubuntuforums and AskUbuntu as Sudodus, it never once occurred to me that you were not a native English speaker. Your command of the language is excellent.

PM me the URL of any pages you would like me to review.

4 Likes
32

2 posts were split to a new topic: Mkusb, iso2usb, Win32DiskImager, ISOBoot Documentation Review