352165 - Improve the "Bug Writing Guidelines"

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement)

Description

[eli]

I wrote Bugzilla's bug writing guidelines eight years ago while I was a
software test engineer at Netscape. I've revised it (with extensive help from Vera Horiuchi), and
attached it for review.

    Why update this tutorial?

    A lot has changed in eight years:

    * Many of the products I mentioned are obsolete (Mac OS 9, Internet
Explorer 5, Macsbug, etc.)

    * People have shrinking attention spans when reading web pages. We can't
count on people reading every single word and tangent. Content must be quick
to read or it will be ignored.

    (I receive monthly e-mails from annoyed people who won't report a bug
because the tutorial was too long to read.)

    * My own standards are higher -- I'm now a graduate student in technical
communications at the University of Washington.

    So, after talking with Max and Gandalf, I've updated the Bug Writing
Guidelines to better reflect the expectations of today's users.

NOTES:

* I have not verified it for XHTML compatibility. Will do so after the content is approved.

* The only feedback received so far is a request to eliminate the usage of "she", since the reader found it distracting. Where possible to do without introducing awkwardness, I will gender-genericize these phrases.

* Graduate school fall quarter begins on September 17th. I probably won't be available after that date until mid-December.

Comment 1

[eli]

Attachment: Revision of bug writing guidelines

Revision of bug writing guidelines.

See bug #131345 for earlier back-history.

Comment 2

[eli]

Comment on attachment 237744 [details]
Revision of bug writing guidelines

Fixing failed mime type auto-detect.

Comment 3

[eli]

Attachment: Diffs from previous version

Here's all the changes made.

Comment 4

[Gervase Markham [:gerv]]

Eli: for future reference, "diff -u" (unified format) is normal for patch exchange.

Exactly which version of the bug writing guidelines did you base your changes on, and from where did you get it? 

There are some things which are a little odd. For example, did you mean to remove some names from the list of contributors at the top? And yet not add yourself or Vera?

Gerv

Comment 5

[eli]

Attachment: Bug writing diffs (in unified format)

Oops, *now* I see how to obsolete a previous attachment. Sorry - first time.

Comment 6

[eli]

Hi, Gerv --

First, thanks. Updated with a 'diff -u'.

I based the file on the 'bugzilla-2.22' download tarball on the website. I now realize, of course, I should have used the 'bugzilla-2.23.2' development snapshot. However, a diff on these two files indicates that bug-writing.html.tmpl hasn't been updated since the 2.22 release.

That said - Whoa! Did I actually check in the wrong file? Umm...the depth of embarrassment I feel right now does not belong in Bugzilla.

 

Comment 7

[eli]

Attachment: Revision of bug writing guidelines (this time, for real)

Sorry, I attached the file from the wrong bug. (!)

Replacing with correct file (and with Vera's credit added).

Comment 8

[timeless]

Comment on attachment 237751 [details] [diff] [review]
Bug writing diffs (in unified format)

>+<h3>What Makes a [% terms.Bug %] Report Useful?</h3>

this will have to be [% terms.aBug %] or something.

>+  <p>Useful [% terms.bug %] reports get [% terms.bugs %] fixed. 

overuse of the terms.bug token, drop the first use, please? :)

>+  A useful [% terms.bug %] report has two qualities:</p>

Can we skip it here too?

And can you stop posting patches long enough for me to comment? ;-)

Comment 9

[Wayne Mery (:wsmwk)]

does this encompass bug 237796?

Comment 10

[Gervase Markham [:gerv]]

Attachment: CVS diff of previous attachment against tip

Comment 11

[timeless]

Comment on attachment 237753 [details]
Revision of bug writing guidelines (this time, for real)

>  <p>Simply put, the more effectively you report [% terms.abug %]

I don't like |effectively you report| one bit.

The <cleaner|more understandable> your terms.bug report is ...

>    <li><b>It's Reproducible.</b> Developers usually prefer to fix bugs they can actually see. If an engineer can't reproduce the [% terms.bug %],

>    she'll probably stamp your [% terms.bug %] report 

< your report will probably be stamped ...

>    "WORKSFORME" or "INVALID"

> and move
< as the developer moves

> on to the next
>.
<one.

> <br>

>  <a href="query.cgi">search page</a> to determine whether your [% terms.bug %]
>  is a known [% terms.bug %].</li>

terms.bug overuse. => is known.

>  <li>Reproduce your [% terms.bug %] using a recent build. 

"build" is a technical term, not everyone uses it. Should we eschew it? ;-(

> <li>From [% terms.Bugzilla %]'s main page, choose 

Some day we're going to need terms.Bugzilla_s :(

> "<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>

I wonder if we should worry about admins customizing the front page w/o realizing that the guidelines include steps along it.

> <li>Select the product in which you've found a [% terms.bug %].</li>

terms.abug

> <li>Enter your e-mail address and password, and click the "Log in" button.

Sometimes it isn't an e-mail address. My bugzilla gives me an http auth dialog.

> (If you don't have a password, follow the on-screen instructions to obtain
> one.)</li>

This doesn't always exist, it might be possible to know if it does.

>  <p><b>Where did you find the [% terms.bug %]?</b></p>

>    <p><b>Product:</b> In which product did you find the [% terms.bug %]?<br>

someday soon this might already be terms.Product/terms.product

>     You just specified this on the last page, so you can't edit it
>    here.</p>

If there's only one product then the product chooser doesn't exist at all.

>    a [% terms.bug %]. (Click  the Component link to see a description of each component.)</p>

terms.abug (i'm going to stop flagging this). Extra whitespace before 'the' (i'll never flag this again, since html really doesn't care).

>    <p><b>Severity:</b> How damaging is the [% terms.bug %]?<br>
>     This item defaults to 'normal' severity. (Click on the Severity link to see
>     a description of each severity rating.<br>

damaging is enhancement... awkward :(.

> If you'd prefer
>    to directly assign the [% terms.bug %] to someone else, enter the person's
>    e-mail address.

sometimes there's a picklist instead of an entry field, someone should help you deal w/ that unfortunate case.

> (To see the list of default engineers for each
>    component, click the Component link.)</p>
>
>    <p><b>Cc: Who else should receive e-mail updates on changes to this 
>    [% terms.bug %]?</b><br>
>    List the e-mail addresses of other people who should receive
>    an update whenever the [% terms.bug %] report changes. Enter as many e-mail 
>    addresses as you'd like, separating them by spaces or 
>    commas. Important: E-mail updates are only sent to people who have 
>    [% terms.Bugzilla %] accounts.</p>

Again, sometimes people foolishly use pick lists.
Note that your statement should be clearified to somehow indicate that Bugzilla normally won't accept addresses unless they correspond to user accounts.

>     Provide a detailed problem report. A 
>     [% terms.bug %]'s recipients usually expect the following 
terms.Abug (yeah, we have lots of these fun tokens, last time I warn about any of them).


>The application crashed. Stack crawl appended below from MacsBug.

MacsBug is mostly gone, should this be CrashReporter.app? :)

Note that CrashReporter.app has issues, all of our mac devs complain when people paste the logs (they're too long), and dr watson is longer and less useful. A hint about attachments might unfortunately be useful. But at least some hint that for stack traces, only the stack and not the other garbage should go into the bug.


>        <li><b>Windows:</b> Note the type of the crash, and the module that the
>        application crashed in. (e.g. access violation in apprunner.exe)</li>

ah, here's the place to say don't include the compatibility report or drwatson info.

>        <li><b>Mac OS X:</b> attach the "Crash Reporter" log that appears upon crash. Only include the section immediately below the crashing thread, usually titled "Thread 0 Crashed:".


Should use use <li> instead of 2.?
>  <p><b><a name="summary"></a>2. How and Why to Write Good [% terms.Bug %]
>  Summaries</b></p>

Comment 12

[timeless]

yes, the 'she' bit bothered me. sorry. i can't help it.

also, please wrap lines to 80 chars ;-)

Comment 13

[Gervase Markham [:gerv]]

Comment on attachment 237757 [details] [diff] [review]
CVS diff of previous attachment against tip

>+<h3>What Makes  Report Useful?</h3>

As timeless says:
a [% terms.Bug %] -> [% terms.aBug %]

It's that a/an thing.

>+    <li><b>It's Reproducible.</b> Developers usually prefer to fix bugs they can actually see. If an engineer can't reproduce the [% terms.bug %],

The rest of the file has carriage returns every 80 chars or so; it would probably be best to make new text consistent with that.

>+    she'll probably stamp your [% terms.bug %]
>+    report "WORKSFORME" or "INVALID" and move on to the next. <br>

I'd argue for "he" throughout, as the grammatically correct gender to use for persons of unknown gender. (It's the same principle as that under which one "she" for ships, even those with male names.) However, the Political Correctness Police would probably arrest me if I insisted, so perhaps you might care to use singular they? :-)

>+<ol>
>+  <li>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s 
>+  <a href="query.cgi">search page</a> to determine whether your [% terms.bug %]
>+  is a known [% terms.bug %].</li>

We might want to link directly to the form of search best used here:
query.cgi?format=specific

>+ <li>Enter your e-mail address and password, and click the "Log in" button.
>+ (If you don't have a password, follow the on-screen instructions to obtain
>+ one.)</li>

If necessary, enter...

>+    to directly assign the [% terms.bug %] to someone else, enter the person's
>+    e-mail address. (To see the list of default engineers for each
>+    component, click the Component link.)</p>

We can probably remove that latter statement; it's not particularly useful. Why would they bother clicking the link to look at the list?

>+    <p><b>Cc: Who else should receive e-mail updates on changes to this 
>     [% terms.bug %]?</b><br>
>+    List the e-mail addresses of other people who should receive
>+    an update whenever the [% terms.bug %] report changes. Enter as many e-mail 
>+    addresses as you'd like, separating them by spaces or 
>+    commas. Important: E-mail updates are only sent to people who have 
>+    [% terms.Bugzilla %] accounts.</p>

You probably want to say "Important: you can only specify people who...", to make it really clear.

>+     A useful summary is "<tt>PCMCIA install fails on Toshiba Tecra
>+    780DVD w/3c589C</tt>". Examples of bad summaries would be "<tt>Software fails</tt>" or "<tt>install
>+    problem</tt>".<br>

Is this example unnecessarily geeky?

Gerv

Comment 14

[timeless]

I think it's kinda hard to write a non geeky example. maybe something about coffee brewers or capacino machines?

please excuse my spelling. I drink tea, and i'm having a hard time coming up with an example of tea going wrong.

We should also consider leading people to guided, note that in guided the component descriptions are readily at hand, so the click link thing is less necessary. But as a transition from guided to normal the link is useful.

Comment 15

[Kevin Benton]

Comment on attachment 237753 [details]
Revision of bug writing guidelines (this time, for real)

Hi Eli.  First, thanks for contributing.

To utilize our review process, when you're ready to request approval for your update, please set the review flag to ? on your attachment.  This helps the reviewers know that your patch needs to be looked at. :)  If you decide to cancel your review request, you can clear the flag (by making it blank again).  If we agree with your update, a reviewer will set the flag to +.  If there are problems that require changing, we'll set the flag to -.

It's important for the reviewers to be able to see what you're proposing to change.  It's also important that we utilize patches to make it possible to trace things backward in case certain updates or parts of updates need to be rolled back.  To do that, simply use the following steps:

1) cvs co Bugzilla
(as documented at the Bugzilla Download page - http://www.bugzilla.org/download/)
Note: if it's been a while since your last cvs co, you may want to use cvs up -CA to bring your source up to date before you proceed to the next step.
2) Make your changes
3) cvs diff -u >/some/other/dir/filename.diff (do this from the bugzilla directory to capture all your changes to all files in Bugzilla)
4) Upload your cvs diff -u output as an attachment to this bug.
5) Set the review flag to ? for your attachment.

Here are comments specific to your proposed updates:

An index at the top of this document and anchors below would be very helpful.  That would allow others to reference specific areas of your tutorial more easily.  It would also make it easier for users to jump to specific areas of your document.  I can think of one case (for example) where I would point users to the section on writing a good summary directly from the bug entry screen.

As previously suggested, consider reducing the use of [% terms.*bug %] in your document.  While it's less ambiguous to use [% terms.*bug %] multiple times in a sentence or paragraph, the use of a pronoun is generally equally clear and reads more quickly.  Readers are generally pretty good at figuring out what is meant.  Example: If an engineer can't identify your [% terms.bug %] by its summary, it may be ignored when skimming through a 10-page list.<br> (removed second [% terms.bug %]).

<h3>What Makes a [% terms.Bug %] Report Useful?</h3>
should be changed to
<h3>What Makes [% terms.ABug %] Report Useful?</h3>
If you really want terms.aBug, you'll also need to update templates/en/default/global/variables.none.tmpl

Nit: I noticed that you chose not to capitalize words in the "Found a new [% terms.bug%] in a recent build? Report it." At first glance, it looks like all the other headings at that level are capitalized as titles.

Nit: Consider using style tags rather than coding <h3> and <b> into your document.  For example, by using <div class="mediumheading"> over <h3>, it's a lot easier to make adjustments to how all the mediumheading div's look simply by changing the style sheet oncen (over having to change all the <h3>'s and </h3>'s in the document.  The same applies for your <b> </b>, <tt> </tt> and other text formatting tags.  While it took me a significant amount of time to convert my methodology to using <div> and <span> whenever possible, I'm reaping tremendous rewards when it comes time to reformat the look/feel of my documents.  CSS rocks! :)

Thanks again for your contribution and I'm looking forward to seeing more from you. :)

Comment 16

[Hermann Schwab]

May be you can add a hint or two. 
Add CC: 
a lot of reporters lately unnecessarily add themselves, don't know they are automatically getting bugmail from their bug.

Additional Comments:  
Some reporters don't know where to add a comment, when asked to answer a question. I myself, having read bugs for a year before I wanted to comment, asked somebody. I was so used to quickly scrolling down to the comments that I didn't see that huge empty textarea anymore. A year later, I got a mail asking this. There are a lot of bugs where the reproter doesn't comment, and sometimes opens another bug for the same issue. Sometimes I get reporter's comments per mail from the reporter, not from the bug.

Referring to bugs, comments, talkback numbers: 
Often a lengthy URL is used, even by experienced developers. Besides better readability, Linkifying has the advantage of giving you the bug's title on hover. To linkify, write Bug 352165 instead of 352165 or https://bugzilla.mozilla.org/show_bug.cgi?id=352165. Comment 0 refers to this bug's Description:, bug 237796 comment 0 to another one. Bugs 237796, 352165 don't linkify because of the 's' in Bugs, Bug 237796, 352165, try yourself.

But maybe something like this should be linked as Help into the header and footer just following 'Enter new Bug'

Comment 17

[eli]

Sorry for the delay -- I've held off until Vera and I have had a chance to review all of the feedback provided together.

We're going to make the changes that make sense and/or comply with industry conventions for professional technical communications. Do note that we have a limited amount of time available. I regret cannot research additional suggested cross-platform bug submission comments, such proper usage of Dr. Watson. As provided, there is not enough information available in this bug to document it satisfactorily. 

Kevin, thank you in particular for your comments. Regarding migrating from HTML to CSS formatting, would you know of another Bugzilla document I could use an example of what styles are available within Bugzilla templates? My CSS knowledge is limited, but I'm sure I can do it given such an example (except for the CSS equivalent of blockquotes - sorry!).

I'll get started on this tomorrow, and try to be done then.

Comment 18

[eli]

Attachment: Second revision bug writing document

This addresses all of the suggestions and feedback received that Vera and I considered suitable. 

If there are particular feedback items that you provided which were not addressed, and which you strongly believe to be crucial to the usability of this document, please let me know which ones, and we'll reply accordingly.

Please note that these issues are not addressed in this version:

* Migrating HTML formatting to CSS formatting 
* XHTML validation

I'd like to do these, however, I am unable to find the information necessary to complete these two items. I would be happy to do them by Friday given access to said information.

Comment 19

[eli]

Additional comments:

>> "<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
> 
> I wonder if we should worry about admins customizing the front page w/o
> realizing that the guidelines include steps along it.

Perhaps it's worth filing a bug to add a comment to that page's HTML as to other locations where it's referenced within Bugzilla by the default name?

No action taken - beyond scope of document revision.

>> +    she'll probably stamp your [% terms.bug %]
>> +    report "WORKSFORME" or "INVALID" and move on to the next. <br>
> 
> I'd argue for "he" throughout, as the grammatically correct gender to use for
> persons of unknown gender. (It's the same principle as that under which one
> "she" for ships, even those with male names.) However, the Political
> Correctness Police would probably arrest me if I insisted, so perhaps you 
> might
> care to use singular they? :-)

Just to be clear, it is *not* grammatically correct to use "he" for people of unknown gender. This is an out-of-date style convention, and is no more accepted or grammatical than using "she" to refer to a generic individual.

All corporate style guidelines I've personally reviewed prohibit the "he" style convention convention.

I have updated the document to reflect the Apple style guidelines of gender-neutrality.

Comment 20

[eli]

Attachment: CVS diffs of previous attachment from tip

And here's the CVS diff against the tip for the latest version, using Kevin's instructions.

Comment 21

[eli]

Comment on attachment 238309 [details] [diff] [review]
CVS diffs of previous attachment from tip

Please note that CSS fixes and XHTML validation aren't contained in this attachment.

If you can point me to any FAQ or place with any hint on how to do this, I'd be happy to do a third take at the document with those changes.

Comment 22

[eli]

(specifically, the W3C XHTML Validator rejects the templatized files, so I'm not sure how to do an XHTML validation on them as-is).

Comment 23

[Gervase Markham [:gerv]]

Eli: that's great. Don't worry about CSS etc; we can fix that stuff up if necessary. Focus on the content, and don't succumb to those who are advocating mission creep ;-)

Gerv

Comment 24

[victory <[e-mail]>]

Eli:
perhaps & must be &
wrap long lines ;-)

Comment 25

[Gervase Markham [:gerv]]

Comment on attachment 238309 [details] [diff] [review]
CVS diffs of previous attachment from tip

Looks good to me.

Gerv

Comment 26

[eli]

Thanks Gerv!

Umm...I don't have check-in privileges. Would anyone like to take this bug?

Comment 27

[timeless]

Comment on attachment 238309 [details] [diff] [review]
CVS diffs of previous attachment from tip

>+  <li>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s 
>+  <a href="query.cgi?format=specific">search page</a> to determine whether your [% terms.bug %]
>+  is known.</li>

this doesn't explicitly spell out that duplicate reports are bad/unwanted.

>+Can't find your [% terms.bug %] with a recent build? Let's report it.
>+</blockquote>

i'm pretty sure this doesn't say what we mean.

we want to say ~ if you can reproduce the problem but can't find a report for the problem, then report the problem ~.

You didn't address my magic one product problem here:
>+ <li>Select the product in which you've found [% terms.abug %].</li>

Heh, well, this kinda skirts the "how do you log in", but is "log into" spelled acceptably? :)
>+ <li>Log into [% terms.Bugzilla %].</li>

>+    <p><b>Severity:</b> How damaging is it?<br>

I still don't like "how damaging is it". It's enhancement damaging just doesn't roll off the tongue.

This still should have magic to deal with places where you aren't using email addresses or don't have a text entry field:
>+    to directly assign the [% terms.bug %] to someone else, enter the person's
>+    e-mail address. (To see the list of default engineers for each
>+    component, click the Component link.)</p>

ibid:
>+    <p><b>Cc: Who else should receive e-mail updates on changes to this 
>     [% terms.bug %]?</b><br>
>+    List the e-mail addresses of other people who should receive
>+    an update whenever the [% terms.bug %] report changes. Enter as many e-mail 
>+    addresses as you'd like, separating them by spaces or 
>+    commas. Important: You can only enter people who have 
>+    [% terms.Bugzilla %] accounts.</p>

Comment 28

[eli]

> (From update of attachment 238309 [details] [diff] [review])
>> +  <li>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s 
>> +  <a href="query.cgi?format=specific">search page</a> to determine whether 
>> your [% terms.bug %]
>> +  is known.</li>
> 
> this doesn't explicitly spell out that duplicate reports are bad/unwanted.

I do not think this is necessary to explicitly spell out. I think it's contextually obvious when we have already asked the user to first search for a duplicate before reporting a bug.

Realistically, you wouldn't go search to see if someone reported a bug, discover that *yes* someone has, and then spend a half-hour to re-report it from scratch with that knowledge?

 >> +Can't find your [% terms.bug %] with a recent build? Let's report it.
>> +</blockquote>
> 
> i'm pretty sure this doesn't say what we mean.
> 
> we want to say ~ if you can reproduce the problem but can't find a report for
> the problem, then report the problem ~.

This one, I agree could be improved. I have updated it and will submit a new version.

> You didn't address my magic one product problem here:
>> + <li>Select the product in which you've found [% terms.abug %].</li>

I have not personally used a Bugzilla installation with fewer than two products. In this case, I expect that if it's already selected, the user will realize he or she does not need to specify the product manually. 

It is not necessary to give instructions like "If you find that you are already standing, you can ignore the instruction to stand up." In fact, it's distracting to the reader.

(Don't forget that we are writing for a technical user base.)
 
> Heh, well, this kinda skirts the "how do you log in", but is "log into" 
> spelled
> acceptably? :)

Yes, it's in fact spelled correctly. Check your favorite grammar or style guideline set.

>> + <li>Log into [% terms.Bugzilla %].</li>
> 
>> +    <p><b>Severity:</b> How damaging is it?<br>
> 
> I still don't like "how damaging is it". It's enhancement damaging just 
> doesn't
> roll off the tongue.

We consciously chose not to change this. Since you spent a lot of time providing feedback, I'll give you the complete explanation of why we left it as-is.

This document exists to communicate how to write an effective bug report. Although we want the content to be accurate, it's not necessary for everything to be precise at the cost of clarity. 

Documentation isn't like software: a user may not care how many lines of code you had to write, but they sure as hell care if they have to read extra words to get their job done. That's right - by adding words to clarify something, you increase the length of the document, thus making it *less* readable. 

Contrast this with precise works of documentation: for example, 20-page legal contracts. Or perhaps 800 page reference books on OS or network stack behaviors?

That's not what our users want.

Vera and I are confident that a reader will understand what this means, and that's what matters. We can't think of a better way to phrase it, or a way to address this without extending the sentence length and complexity. So, we prefer to leave it unchanged.

> This still should have magic to deal with places where you aren't using email
> addresses or don't have a text entry field:
>> +    to directly assign the [% terms.bug %] to someone else, enter the 
>> person's
>> +    e-mail address. (To see the list of default engineers for each
>> +    component, click the Component link.)</p>

This is beyond the scope of this revision, and of the skill set of the authors. Please feel free to file an enhancement request or bug for a future revision.

I think we're at the point where we are not really making substantive improvements to the document. Thus, I am submitting the next version as the final draft; I do not believe it warrants further revisions. However, if additional changes are needed, I will be available again after Dec 15th, 2006.

Comment 29

[eli]

Attachment: Final draft of revised bug writing guidelines

Addresses comment number 24 and 27.

(Re: Comment #24 - note that I did not fix line wrap. Not sure what to do here without potentially introducing new problems. Whoever checks this in is welcome to fix that.)

Comment 30

[eli]

Attachment: CVS diff of final draft against tip

Here's the final diffs. 

The only two changes made from prior version were those cited in the previous comment (replacing the one "&" with "&", and clarifying an ambiguous phrase.)

Comment 31

[eli]

Gerv, could you possibly kick this to whomever takes it from here? I'm done with my part of the show. 

Note that I'm officially now unavailable for 12/15/2006.

Thanks,

Eli

Comment 32

[Gervase Markham [:gerv]]

Requesting approval.

Gerv

Comment 33

[timeless]

Comment on attachment 239280 [details] [diff] [review]
CVS diff of final draft against tip

> Realistically, you wouldn't go search to see if someone reported a bug,
> discover that *yes* someone has, and then spend a half-hour to re-report it
> from scratch with that knowledge?

i've read enough firefox reports that yes, i don't think you can assume the level of common sense of the people touching this bug :(.

> I have not personally used a Bugzilla installation with fewer than two
> products. In this case, I expect that if it's already selected, the user will
> realize he or she does not need to specify the product manually. 

fwiw what happens is you don't get the product selection page. when we temporarily switched to having 2 products, our users complained that they couldn't figure out how to report a bug! 

> (Don't forget that we are writing for a technical user base.)

This point i disagree with, most of the people i've watched poke bugzilla aren't technical, or at least not usefully technical. i deal with lots of end users reporting bugs, and i think they'd be willing to read this document, but they don't discover things unless they're spelled out.

note: I'm not saying that i *like* dealing with non technical users. just that they exist and tend to complain fairly loudly.

--

that said, let's get this in, everything else can be dealt w/ as new bugs.

Comment 34

[Dmitry Repkin]

It will be good to replace plaintext "WORKSFORME" and "INVALID" by [% resolution_descs.WORKSFORME %] and [% resolution_descs.INVALID %]

Comment 35

[Frédéric Buclin]

Comment on attachment 239280 [details] [diff] [review]
CVS diff of final draft against tip

This patch doesn't pass tests. I will update it myself with comment 34 addressed too.

Failed Test     Stat Wstat Total Fail  Failed  List of Failed
-------------------------------------------------------------------------------
t/005no_tabs.t     1   256   412    1   0.24%  360
t/009bugwords.t    1   256   272    1   0.37%  220

Comment 36

[Frédéric Buclin]

Attachment: patch checked in

OK, now it passes tests, WFM and INVALID have been replaced by their resolution_descs.FOO equivalent, and I also wrapped long lines.

Comment 37

[Frédéric Buclin]

Reassigning bug to patch's author.

Comment 38

[Frédéric Buclin]

Checking in template/en/default/pages/bug-writing.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/pages/bug-writing.html.tmpl,v  <--  bug-writing.html.tmpl
new revision: 1.5; previous revision: 1.4
done