Closed Bug 109311 Opened 23 years ago Closed 22 years ago

Bugzilla Users' Best Practices Guide

Categories

(Bugzilla :: Documentation, enhancement, P3)

Product:
Bugzilla
Component:
Documentation
Version:
2.15
Type:
enhancement

Tracking

()

Status:
RESOLVED FIXED
Milestone:
Bugzilla 2.18

People

(Reporter: CodeMachine, Assigned: bz)

Details

We need to let users know how they should be using Bugzilla.  This document
should not be a part of the Bugzilla Guide, it should be linked from the
Bugzilla pages.  It should be templatised so it can be easily customised by
installations and bmo can add their own Mozilla-specific stuff.

To demonstrate what I mean, the following comes to mind:

1. Don't use sigs in comments.  Everyone knows who you are.
2. Don't add comments saying what you're doing, as they cause people to receive
e-mail who aren't interested.  Only comment if you have something to say about
_why_ you're doing something.
3. If you need to link multiple bugs to one bug via dependencies, edit the one
bug rather than the many so as to reduce bugmail sent out on the one bug.

Let's try to keep this non-controversial (ie no "take XXX discussions to
newsgroups").

Asa can you please CC any people who might have something to say here.
Also add, please no debugging output, logfile output, or other large amounts of
cut and pasted text to be put into a comment that could more appropriately be
uploaded as an attachment. Small snippets of output that show individual errors
or offending lines are fine.
This is an excellent idea. Perhaps have a short explanation of the "Bugzilla
process" that is used in many bugzilla sites (triage, peer review, status and
resolutions) also MattyT?
Priority: -- → P3
Target Milestone: --- → Bugzilla 2.18
An useful addition would be : reporters do not need to add there mail address in
the cc list (I often see that one)
Some people add themselves to CC so they can not receive mail for most of the
bugs they've reported, are assigned to etc.  If we could do this we would fix it
in Bugzilla.  Maybe if and when we have personal keywords we can use them for
filtering instead.  The reporter abandonment proposal would go part way (bug
#94247).
The docs should always be up-to-date when we release.  Forgot to exclude
Documentation when I mass-retargetted.
Target Milestone: Bugzilla 2.18 → Bugzilla 2.16
Target Milestone: Bugzilla 2.16 → Bugzilla 2.18
Large amounts of subsidiary information (test cases, sample outputs, patches,
etc), should be added as attachments rather than a part of comments.
a few more suggestions for guide:

*trim screenshots. no need to show the whole screen if you're pointing out a
problem with a single button, piece of text,icon, etc. 

*you do not need to comment when adding or removing an email from the cc: list. 

*you do not need to put "any url" or similar strings in the URL field. 

*please type "bug" before bug numbers so that they get linkified by bugzilla. 
Cc'ing timeless, he'll need to reconcile this with his own guide, which he often
breaks.
* don't attach simple test cases (e.g. one html file and one css file and one
image) as a ZIP file. Instead, upload them in reverse order and edit the
referring file so that they point to the attached files.
methinks there should to be a link to
http://mozilla.org/quality/browser/navigator-who2bug.html --whose aim is to more
quickly direct browser bugs to the appropriate developers and qa.
Try to make sure that everything said in the summary is also said in the first
comment.  Summaries are often updated and this will ensure your original
information is easily accessible.
Don't press stop in the browser or surf to another webpage until the changes
have all been submitted for your bug (process_bug.cgi is finished loading). If
you do, all of the changes won't be completed. (Is this a bug?) 
yes. That's a bug. Bug 104589 specifically.
As well as talking about "bug" for linkifying, talk about the "comment" syntax
too.
1. Do not HTML escape HTML source.
   <HTML>
   <HEAD><TITLE>This is annoying...</TITLE></HEAD>
   <BODY>

2.     There is no need for indenting text like this.
       White    space    will    be    preserved.

3. Speaking of the bug 1234 syntax, it is a tad annoying to read "See bug 12345
   in Bugscape for more info."  I realize that nscp has its own Bugzilla 
   install, but it is annoying to have bug 12345 linked to the b.m.o bug 12345.
   Direct links to Bugscape would work better.  Not only would it make it less
   annoying for Joe MozillaUser, but also for NSCP people who can then just
   click on a link directly to the bug instead of having to manually go to
   bugscape and type in the bug number.  If anyone refers to bugzilla.redhat.com
   or bugzilla.gnome.org or any other bugzilla install, I expect the same thing.
We might want to incorporate the bug writing guidelines into this document.

Also, its usually a good idea to separate large patches into small patches if
feasible, because they are easier to review and can be checked in separately.
If you feel your bug was duped incorrectly, please question it in your bug, not
the bug it was duped to.  Feel free to CC the person who duped it if they are
not already on the bug.

If you feel your bug was otherwise resolved incorrectly, please feel to re-open
it and address any issues that were raised in the bug (missing information/steps
to reproduce, need to try on a recent, as opposed to 5 month old build, etc). 
Always download the latest build and attempt to reproduce before re-opening a bug.
Barnboy changed his email address and opened a new account instead of having the
address changed on his existing one.  Reassigning all docs bugs to his new account.
Assignee: barnboy → mbarnson
OK, most of this has gone into the Hints and Tips section of Using Bugzilla in
the Bugzilla Guide. Please file further bugs if you have more ideas.

Gerv
Status: NEW → RESOLVED
Closed: 22 years ago
Resolution: --- → FIXED
The Bugzilla Guide is not the appropriate place for this.  This is user
documentation and it should be a part of online help.
The Bugzilla Guide is a guide for all Bugzilla users and admins - it now
specifically has a user manual section. So that's alright.

Gerv
We significantly shortchange our users by doing this.  Admin and user
documentation are two different things and should be treated as such.

In particular, user documentation should be administrator customisable, and be
able to customise itself to the installation settings.  This implies it should
be templates, and not a part of the Bugzilla Guide.
OK, I'll buy that. So you are saying that all the user documentation should be
customisable page.cgi pages (see bug 170213)?

Gerv
QA Contact: matty_is_a_geek → default-qa
You need to log in before you can comment on or make changes to this bug.