Outdated Documentation

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

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

I can think of two ways:

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

1 Like

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

1 Like

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

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

@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

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

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