131345 - Placeholder bug for revision to Bugzilla distribution of Bug Writing Guidelines

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[eli]

I'd like to revise the Bugzilla version of the Bug Writing Guidelines in the
next few days. 

It was originally written to discourage sloppy bug writing, rather than to
detail  best practices. Moreso, I've written about 1,500 more bugs since writing
the original guidelines, and learned a lot more about writing non-sucky bugs
that I'd like to incorporate.

Will attach a revised version for feedback and further revision in the next few
days.

(Filing while in Asa's cube, so that I actually do this.)

Comment 1

[Zach Lipton [:zach]]

Can it be? The famous Eli Goldberg? Pushing to 2.16, this would be great 
to have in. Thanks for doing this.

Comment 2

[Zach Lipton [:zach]]

btw, you don't have to finish this for the 2.16 release (coming up soon). 
Feel free to push it up later if you want more time since this doesn't really 
go with the rest of the sgml bugzilla admin guide.

Comment 3

[Eli Goldberg]

Attachment: First stab at revision

I've attached a quick stab at the content direction I'd wanted to push the Bug
Writing Guidelines. 

--> This is not a finished draft; I have not edited or proofread it a whit. <--


Does anyone have any applicable comments?

If the content direction is okay, I'll go ahead and convert it to XHTML and try
to figure out the Templatization that Matty mentioned.

Comment 4

[Dave Miller [:justdave]]

HTML 4.01 (either strict or transitional) please.

We don't want XHTML for compatibility reasons.  See bug 47251 (and join the
discussion if you don't agree)

Comment 5

[Gervase Markham [:gerv]]

If this is just a plain HTML document, it does not need templatisation, does it?
Or are we talking about adding the header and footer?

Query - are they not "bug-writing guidelines" rather than "bug writing guidelines"?

The layout looks somewhat strange - in Mozilla at least; the inter-paragraph
spacing is uneven and often too large.

> 0 alt="News">"

This isn't a stray quote mark, but it took me a minute to work out why. Rephrase?

In general, the content is fine. Is there any way of jazzing it up a bit - plain
black-on white documents with no images or breaks in the text are heavy going.

Gerv

Comment 6

[eli]

Re: Templatization. Damned if I know.

Re: Formatting. Sure. I'll fix all that in BBEdit after being sure the content is 
okay.

Comment 7

[Gervase Markham [:gerv]]

Eli: I think the deafening silence can be taken as approval of the content.
Please go ahead and fix the formatting. I believe the current plan is to use
HTML 4.01 of some variety or other, so don't worry about XHTML.

Gerv

Comment 8

[eli]

Attachment: Second stab at revision (HTML 4.01 Transitional compliant)

Have a second stab. 

* It's now HTML 4.01 Transitional. You'd laugh if you knew how ask how long it
took to do this simple task after years of HTML clue atrophy.

* Fixed the typo Gerv mentioned. (I'm personally happy leaving it as without
the dash; don't know of a reason to add it by American grammar.)

* Still haven't edited or proofread it a whit, or checked the page in Mozilla.
Will do that tomorrow.

* Not sure how to improve visual formatting. Gerv, might you have an example
page to suggest what you're thinking of? 

...and in honor of Mr. Lipton (although perhaps 26 hours too late), Debbie
Friedman's performance of "Birchot Havdalah" is playing in the background. ;]

Comment 9

[timeless]

in some instances, products have a release notes document which contains a list 
of well known bugs, if you could encourage people to read them before reporting 
bugs already listed there, QArs would be happy :-)

Cc: Who else should receive e-mail updates on changes to this bug? 
1. suggest that it doesn't normally make sense to cc the account that reported 
the bug, because it will usually get mail

2. e-mail addresses must be separated by commas, with no spaces between 
the addresses. 
I think we support commas or spaces ...

URL
please encourage people not to enter http://N/A or similar.  URLs should be 
useful either because they're valid and point to a problem page, or because 
their invalidity actually relates to the problem.

Expected Results: What the application should have done, were the bug not 
present.
-The text here didn't wrap.

Comment 10

[Gervase Markham [:gerv]]

Attachment: Gerv's version 1

I passed it though HTML Tidy, and then tidied up the HTML by hand. Encouraged
by this success, I made a few clarifying changes to the content. It still
validates as 4.01 Transitional. Eli - are these changes to your liking?

Gerv

Comment 11

[eli]

Looks beautiful. Thanks, Gerv. (I'd used validator.w3.org which had 
passed it; is it no longer a reliable measure of HTML correctness?.)

Would like to make most of Timeless's changes. And add your name to 
the bottom.

Comment 12

[Gervase Markham [:gerv]]

Eli - I'm a little confused. Do you plan to make those changes yourself?

Gerv

Comment 13

[eli]

Hey, Gerv ---

Duh, yes, I was going to go do those last night (and finally do a real 
editing job), but got caught up in work for Yuri's Night. 

Will do today or tomorrow; would you be open to doing a quick check on 
the final document, especially if validator.w3.org isn't catching all the 
HTML problems?

Comment 14

[Gervase Markham [:gerv]]

Sure. No rush; I doubt 2.16 will leave without you :-)

Gerv

Comment 15

[eli]

Sorry, but I caught the flu 48 hours ago, and have been unable to think or 
sit long enough to make the changes.

All will return to normal next week.

Comment 16

[eli]

Attachment: Final draft?

Attached is a final draft of the bug writing guidelines. Changes made:

* Removed the "URL" and "Platform" field descriptions. 
 a. "URL" isn't used in the handful of non-Moz installations.
 b. Don't most projects (Moz excepted) typically just have a single "OS" field,
rather than both "OS" and "Platform"?

* Clarified/simplified dozens of phrases that bothered me, typically due to
ambiguity, passivity, and excessive use of parentheses, or unnecessary
redundancy.

* Timeless's suggestions
 a. Made clear how multiple CC's can be delimited.
 b. Fixed URL issue by removing section entirely.
 c. Gerv fixed the wrapping earlier on Expected Results.

Comment 17

[eli]

[Duh, never marked assigned.]

Oh, also:

- Yes, I did re-verify it as HTML 4.01 Transitional compliant 
(validator.w3.org)

- Timeless, I didn't make the change about explicitly pointing out that CC'd 
oneself isn't necessary. We didn't have problems with it at Eazel, at least. 
Has this become a widespread problem to warrant mentioning? 

Comment 18

[Gervase Markham [:gerv]]

> the more likely she'll expediently fix it.

Is this correct English?

> rather than those in a code base that's hundreds of bug fixes obsolete. 

This takes some understanding. Can we rearrange to simplify?

"rather than in an old code base; after all, the bug you are reporting may have
already been fixed."?

Other than those two queries, this is ready to go. r=gerv.

Gerv

Comment 19

[eli]

Hey, Gerv ---

For #1, it's correct Americanish to the best of my knowledge. "she'll 
expediently fix it" may be a split infinitive (?), but so is "To Boldly Go Where 
No One Has Gone Before." 

For #2, replaced with "Engineers tend to be most interested in problems 
affecting the code base that they're actively working on. After all, the bug 
you're reporting may already be fixed."

Comment 20

[eli]

Attachment: Final draft. Really.

Here it is. Have fun. Who gets to check this in?

Comment 21

[Gervase Markham [:gerv]]

2xr=gerv.

Checking in bugwritinghelp.html;
/cvsroot/mozilla/webtools/bugzilla/bugwritinghelp.html,v  <--  bugwritinghelp.html
new revision: 1.2; previous revision: 1.1
done

Checked in.

Gerv