Creating a lean Reporting Bugs page

[bashfulrobot]

Hey, @popey Maybe the “How to file a bug” could either link to or be based on the info located at the link below.

https://help.ubuntu.com/community/ReportingBugs

That is what I usually link to when people need help with that.

[popey]

Referring threads to more appropriate sites

That is what I usually link to when people need help with that.

I used to too. But that page is an impenetrable wall of text which is very intimidating for new users. I’d love for us to distil that down to something more digestible for new people. I realise bug reporting is a complex issue, but this page is quite the hurdle for people to overcome just to tell us our software (or website) is broken!

Volunteers welcome, I’d love to help with that, if anyone is willing!

[bashfulrobot]

In theory we could distill it down, and then link to the original for the deep dive. I guess the first thing would be to determine the key points that have to show in the lighter article.

[flocculant]

Got to agree - I’ve been kicking around since mid 2007 - I hate that page. I hate having to read it. I hate having to point people at it.

Happy to help do something about the ‘issue’ in general.

Given that it’s such a monstrously long and detailed page in the first place, if we decide to do something about it - then communication is going to be key.

The one good thing about that wiki page is it has a contents list, so perhaps we could have a shareable doc somewhere - one for the contents so that people can claim a section - then seperate docs for each of the sections so we’ve then got our precis to build a readable for the average person to use.

Maybe use etherpads?

That wiki page is currently set to immutable - so people aren’t going to just be able to edit it.

[popey]

Ok, how about those who are interested get involved here:- http://pad.ubuntu.com/ReportingBugs

In my mind we should strive for ABC - Accuracy, Brevity, and Coherence. If we can agree on the sections at the top we can then divide them up between us and prototype a new guide.

I’ll split this off to a new conversation too.

[ads20000]

I’m not sure I’d be able to contribute but I’m guessing quite a lot of people can’t use pad. Would it make more sense to have that on a more open platform (I may be speaking nonsense)?

Edit: oh flocculant said etherpads so I looked it up…interesting…can it not be set up more flexibly so that at least certain docs can be visible or something?

[ian-weisser]

Etherpad is just as open as Discourse. Same login, too.
You maneuver your browser windows so that whatever you want to be visible is visible.

If you discover that you cannot access etherpad due to permissions (not in the ‘etherpad’ group), merely say so. People with power to change that are already in this thread.

[popey]

I’m not sure I’d be able to contribute but I’m guessing quite a lot of people can’t use pad. Would it make more sense to have that on a more open platform (I may be speaking nonsense)?

Edit: oh flocculant said etherpads so I looked it up…interesting…can it not be set up more flexibly so that at least certain docs can be visible or something?

Etherpad is awesome, it’s like multi-player notepad.

We have used Etherpad for many years. It works well for spinning up a doc very quickly, without danger of external people abusing it. If you need access to the Ubuntu etherpad, just let me have your launchpad account and I’ll add you to the necessary team to grant access.

[bashfulrobot]

hey @popey - I would need access to the page mentioned.

Authorization is required to access http://pad.ubuntu.com/ReportingBugs
Either you have not been granted access to this resource or your entitlement has timed out. Please try again.
You are currently logged in as https://login.ubuntu.com/+id/cdKTdh4. (logout)

My launchpad account is located at: https://launchpad.net/~bashfulrobot

Thanks for your time.

[ian-weisser]

I think there are two problems with the original ReportingBugs page: It tries to do to much for too many users, and it doesn’t clearly mark a path for the first-timer.

Here is one suggested outline for first-time/unskilled reporters. It leverages our existing strengths to get them up that learning curve. The goal is to get them the best chance of a positive interaction, regardless of whether a bug actually gets filed or not. The secondary goal is a high-quality bug report that won’t frustrate a volunteer Triager. It’s obviously not an appropriate workflow for experts:

1. Post a “Is this a bug?” question in a support venue. This is important for a couple reasons. First, it weeds out many settings, duplicates, EOLs, broken hardware, and other non-bugs before they find their way to Launchpad. Second, it provides a knowledgeable human (support) expert’s hand to hold through the complex process - even if the reporter abandons the effort, they still had a positive interaction with a member of the community. With a bit of hand-holding, the reporter collects the appropriate information.

2. Test for the bug in the latest release of Ubuntu using a LiveUSB. Many users stick to LTS, and continue to report minor bugs that were long fixed.

3. Search for the bug in Launchpad. The user now has enough experience and information to use Launchpad’s ‘Search’ properly.

4. Create Launchpad account.

5. Use ‘ubuntu-bug’ to report the bug. There are lots of ways to report the bug, but for the first one lets keep it simple.

6. Monitor the bug to answer the Triager’s questions. If the user is unwilling to reply, the all their previous effort was wasted. They must know up front that they are committing to follow-up.

7. Monitor the bug to test the Developer’s patches. They must know up front that this is a possibility for some bugs.

This is an outline for a ‘Reporting Your First Bug’ page. Should other workflows have a separate ‘Reporting your _____ Bug’ pages? Or is the first report the biggest hurdle?

[ian-weisser]

I have tossed a version of my idea for first-time bug reporters onto the etherpad.
Feel free to pick it apart…and correct the inevitable typos.

[guiverc]

i thought it read well, was clear & easy-to-understand.
[ only one minor change/comment ]

[ian-weisser]

Well that was indeed minor…though appreciated!

Somebody should have more good ideas to add. It’s rather scraped off the wall.

[flocculant]

added a couple of lines - will get back to it soon, been tied up elsewhere

[popey]

I’ll take a look in the morning. Had to get some other things off my plate first. Thanks @ian-weisser

[popey]

Ok, I had a look @ian-weisser and I like the brevity and style, this is great! If nobody has any objections, I’d love to move it here to the hub soon and make it a wiki post so it’s easily discover-able and maintainable. What do you all think?

One of the other big problems people seem to get stuck with though is where to file the bug. For example in 17.10 where do I file bugs with the dock/launcher, or the indicators? Which package controls the system settings? I don’t think that should be covered in this guide, but perhaps we need a separate page which is similar to the Ubuntu Phone “Avengers” which provides a concise look-up table for common packages where we might expect new users to want to file bugs. Give them a short description, the package name and upstream bug reporting location, if appropriate.

I think that could supplement this guide well? Thoughts?

[balloons]

That page has quite a history. And as recently as this past May, folks attempted to create a lean version of the page again, but it didn’t stick: https://help.ubuntu.com/community/ReportingBugs?action=recall&rev=306.

[ian-weisser]

perhaps we need a separate page which is similar to the Ubuntu Phone “Avengers” which provides a concise look-up table for common packages where we might expect new users to want to file bugs.

I think that’s generally covered by Step #1 (talk to a support guru) for first-time bug-reporters. Locating the right package seems an implied task there.

In the Forums or AskUbuntu, locating the package and checking for bug reports is part of many support requests. “Yes, after three days of back-and-forth, that looks like bug #88888. It’s fixed in newer releases of Ubuntu. Why don’t you make a LiveUSB of 17.10 to see if it does the same thing?”

Second-time and later are a different story as they learn new skills each iteration. A look-up table, among many other references and tools, may be quite useful.