As part of the QA retrospective, I’m going to be working on improvements to our Bugzilla documentation. What do you wish was documented better (or at all)? Leave a note here or in QA #685 and I’ll try to cover it.
I want to know more about what should happen after a bug is reported.
Who is this aimed at? If it’s for the general population (inc the user community) then some mention or link out to ABRT might be a good idea.
Pagure vs Bugzilla - why do we have two? When and why should one be used over the other? When and why might someone use one of these versus a mailing list or discussion board?
This needs updating for the new packages application IIRC:
(I wonder if the wiki page should be dropped and the required info added to the quick doc or a series of quick docs?)
Yes! There’s almost certainly going to be both user and contributor docs that come out of this (and they’ll be in the appropriate location, hopefully). ABRT is a good idea.
Ooh, that’s a fun one. I don’t know if it will go in this first round, but it would be good to have some kind of guidance, especially now that GitLab is an option, too.
Looks like it. I’ll try to remember to get that as part of this. It shouldn’t take too long.
That’s the plan, essentially. I’d like to put all of the wiki content into either contributor- or user-facing docs on docs.fp.o. I’m not entirely sure where yet, but that will come as the content takes more shape.
I have submitted and searched bug reports in the past and will of course continue doing so. What I have always found with bugzilla, and I am not all together sure how to rectify it without major facelift. Is that the landing page for it is the same as for any Redhat related product and there is nothing that stands out “Fedora” to me. So for some reason I find it always causes me pause.
As for the doc’s, it’s an undesirable but fortunate side affect of growing the user base, documentation suffers in the short term. There are things like Bugzilla Etigette that are prominent which begs the question why? If you need to enforce code of conduct by users, perhaps the document to address it is not the solution to the root cause. I would think, and having read the threads of content around some bugs, that a lot of vitriol would pour from general users who at that moment “can’t get x to work on Fedora” and what’s Fedora’s collective problem here? Some open source users feel entitled I know. The content of the documents themselves appears fairly robust, with some dated information that should be updated like @ankursinha pointed to.
From the POV of searching bugs, to try to figure out a problem, or help someone else do that, it was a bit frustrating to find a good many cross related issues as separate issues, though this is getting better over the past since there has been an effort in general on bugzilla to rectify that.
I would like to see a slightly more obvious link to Fedora Linux specific issues. I also would like to see some separation of bug reporting based on general use/advanced use, but it is something from a customer service POV that can be difficult to define the line for. It would also be cool to see a bit more automation of linking related bugs to one another to facilitate faster solutions, which in turn should help to reduce abusive bug reporting and possibly some frustration all around.
I’m not quite sure what you mean here. Can you expand on that some?
Just a note, a really short page on reporting bugs was added to the package maintainer docs (it’ll go live in the next build):
Ahh, my early morning brain malfunction. I sign into Bugzilla sometimes with my RH customer portal account, the view is the same for both and I understand why but some form of Fedora Iconography on my FAS user account would be nice. Unless it means my avatar settings are messed up somehow.
Okay, now I understand. That’s outside the scope of documentation. You can file an RFE against Bugzilla, though.
I think Do I need to file a bug? should be changed. That actually says the opposite of what I was expecting, and is part of why maintainers get overwhelmed and users are set up for CLOSED:EOL sadness. The current text means well, obviously, but I think it comes from a “if tickets are good, more tickets must be better!” kind of approach. I think, instead, it should be:
When should I file a bug in Bugzilla?
and cover things like:
- is the issue you are experiencing caused by a software defect?
- if you don’t know, how to use Ask Fedora and other resources to find out
- do you have enough information to file a good bug report?
- if you don’t, how to collect those
- other places that might get more direct results
- upstream communities and trackers
- pull requests for spec files
- Fedora team trackers
- the Changes process
And, I would also suggest changing After Your Bug is Filed to two sections. No, three sections!
- What to expect after your bug is filed
- What to do if your bug is closed without being fixed
- What to do if your bugs don’t get any response
Then, in the next section on Tips by types of bug, I think we should dial “Enhancement requests” way back. I think it should basically say: it is almost always the case that one of the other approaches listed above will get better results.
I mean this in the technical sense. We probably should use a different wording in this document, because I don’t want to get into “It doesn’t have a minimize button and therefore is defective” — in fact, of course, quite the opposite. ↩︎
If someone is bored, my intuition here could be backed up (or theoretically, disproved, but… c’mon) by comparing the outcome of bugs with the
FutureFeaturekeyword to the outcome of other bugs. ↩︎
What to do with the first sometimes unanswerable question: Component:
Users try to describe a problem, a malfunction. But most do not know the answer to this question. I am very curious if ever anybody did file a bug against “adns”.
The form is too much a devel form and too little a users form…
Could folks here please take a look at this and suggest improvements?
You can file issues here with suggestions:
Exactly! (Bold added to your quote for emphasis.) To better support both users and developers, we should make a greater distinction between:
- Symptoms users experience: problems or issues (or as ITIL says, “incidents”)
- Bugs, defects, or faults (which ITIL actually annoyingly calls “problems”)
The important thing is… the first is about what the user experiences — something not working the way the user expects or wants — and that may be caused by a bug (a design or implementation mistake), a defect (failure of the software to meet its design requirements — a defect can itself map to multiple bugs and non-bug work items), or a fault (failure in the environment or resources); or, it might be caused by a user misunderstanding (a failure of UX or documentation, possibly) or some other thing.
I think mixing all of this up causes us real problems, both for people experiencing issues and needing help (or wanting to contribute back by sharing the problems they’re encountering in an open source project) and people trying to do the work to solve those issue (both support community and developers).