Bug 378590 - rewrite and reduce the length of the bug-writing guidelines. Patch by gerv; r=lpsolit,mkanat, a=mkanat

1 files changed, 54 insertions, 219 deletions

diff --git a/template/en/default/pages/bug-writing.html.tmpl b/template/en/default/pages/bug-writing.html.tmpl
index 6df5d5fef..6c6f27dbe 100644
--- a/template/en/default/pages/bug-writing.html.tmpl
+++ b/template/en/default/pages/bug-writing.html.tmpl
@@ -30,157 +30,79 @@
 
 [% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %]
 
-<h3>Contents</h3>
-<ul>
-<li><a href="#why">Why You Should Read This</a></li>
-<li><a href="#useful">What Makes [% terms.aBug %] Report Useful?</a></li>
-<li><a href="#before">Before You Start...</a></li>
-<li><a href="#reporting">Reporting a New [% terms.Bug %]</a></li>
-<li><a href="#more">More Information on Writing Good [% terms.Bugs %]</a></li>
-</ul>
-
-<h3><a name="why">Why You Should Read This</a></h3>
-
-<blockquote>
-  <p>Simply put, the more effectively you report [% terms.abug %], the more
-  likely an engineer will actually fix it. This tutorial teaches novice and
-  intermediate [% terms.bug %] reporters how to write effective 
-  [% terms.bug %] reports.</p>
-</blockquote>
-
-<h3><a name="useful">What Makes [% terms.aBug %] Report Useful?</a></h3>
+  <p>Effective [% terms.bug %] reports are the most likely to be fixed. 
+  These guidelines explain how to write such reports.
 
-<blockquote>
-  <p>Useful [% terms.bug %] reports get [% terms.bugs %] fixed. 
-  A useful [% terms.bug %] report has two qualities:</p>
+<h3>Principles</h3>
 
   <ul>
-    <li><b>It's Reproducible.</b> Engineers usually prefer to fix [% terms.bugs %]
-    they can actually see. If an engineer can't reproduce the [% terms.bug %],
-    it'll probably be stamped "[% get_resolution("WORKSFORME") FILTER html %]" or
-    "[% get_resolution("INVALID") FILTER html %]".<br>
-    <br>
-    </li>
-
-    <li><b>It's Specific.</b> The quicker an engineer isolates the 
-    [% terms.bug %] to a specific area, the more likely it'll be fixed. (If the
-    engineer must decipher your [% terms.bug %], 
-    he or she will waste time cursing you instead.)<br>
-        </li>
+    <li>Be precise</li>
+    <li>Be clear - explain it so others can reproduce the [% terms.bug %]</li>
+    <li>One [% terms.bug %] per report</li>
+    <li>No [% terms.bug %] is too trivial to report - 
+    small [% terms.bugs %] may hide big [% terms.bugs %]</li>
+    <li>Clearly separate fact from speculation</li>
   </ul>
 
-</blockquote>
-
-<h3><a name="before">Before You Start...</a></h3>
+<h3>Preliminaries</h3>
 
 <ol>
-  <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>
-
-  <li>Reproduce your [% terms.bug %] using a recent build. 
-  Engineers tend to be most interested in problems affecting the code base 
-  on which they're actively working. The [% terms.bug %] you're 
-  reporting may already be fixed.</li>
+  <li>Reproduce your [% terms.bug %] using a recent build of the
+  software, to see whether it has already been fixed.
+  </li>
+
+  <li><a href="query.cgi?format=specific">Search</a> 
+  [% terms.Bugzilla %], to see whether your [% terms.bug %] has
+  already been reported.</li>
 </ol>
 
-<blockquote>
-Can't find your [% terms.bug %] in [% terms.Bugzilla %]? And you can reproduce
-it in a recent build? Let's report it.
-</blockquote>
+<h3>Reporting a New [% terms.Bug %]</h3>
 
-<h3><a name="reporting">Reporting a New [% terms.Bug %]</a></h3>
+<p>If you have reproduced the [% terms.bug %] in a recent build and 
+no-one else appears to have reported it, then:</p>
 
 <ol>
- <li>From [% terms.Bugzilla %]'s main page, choose 
- "<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
-
- <li>Select the product in which you've found [% terms.abug %].</li>
-
- <li>Log into [% terms.Bugzilla %].</li>
-
- <li>Fill out the form. Here's what it all means:</li>
-
+ <li>Choose 
+ "<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>"</li>
+ <li>Select the product in which you've found the [% terms.bug %]</li>
+ <li>Fill out the form. Here is some help understanding it:</li>
 </ol>
 
-
-  <p><b>Where did you find the [% terms.bug %]?</b></p>
-
   <blockquote>
-    <p><b>Product:</b> In which product did you find it?<br>
-     You just specified this on the last page, so you can't edit it
-    here.</p>
-
-    <p><b>Version:</b> In which product version did you find 
-          it?<br>
-     (If applicable)</p>
-
-    <p><b>Component:</b> In which component does it 
+    <p><b>Component:</b> In which sub-part of the software does it 
           exist?<br>
-    [% terms.Bugzilla %] requires that you select a component to enter 
-    [% terms.abug %]. (Click the Component link to see a description of each 
-        component.)</p>
+    This field is required.
+    Click the word "Component" to see a description of each 
+    component. If none seems appropriate, look for a "General" component.</p>
 
     <p><b>OS:</b> On which operating system (OS) did you find 
           it?
     (e.g. Linux, Windows XP, Mac OS X.)<br>
-    If the [% terms.bug %] happens on all operating systems, choose "All". 
-    Otherwise, select the OS, or "Other" if your OS isn't listed.</p>
-  </blockquote>
-
-  <p><b>How important is the [% terms.bug %]?</b></p>
-
-  <blockquote>
-    <p><b>Severity:</b> How damaging is it?<br>
-     The default is 'normal' severity. (Click on the Severity link to see
-     a description of each severity rating.<br>
-    </p>
-  </blockquote>
-
-  <p><b>Who will be following up on the [% terms.bug %]?</b></p>
+    If you know the [% terms.bug %] happens on more than one type of 
+    operating system, choose "All". 
+    If your OS isn't listed, choose Other.</p>
 
-  <blockquote>
-    <p><b>Assigned To:</b> Which engineer should be responsible for fixing
-    it?<br>
-    [% terms.Bugzilla %] automatically assigns the [% terms.bug %] to a
-    default engineer upon submitting [% terms.abug %] report. If you'd prefer
-    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>
-
-    <p><b>Cc:</b> Who else should receive e-mail updates on changes to this 
-    [% terms.bug %]?<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>
-  </blockquote>
-
-  <p><b>What else can you tell the engineer about the [% terms.bug %]?</b></p>
-
-  <blockquote>
     <p><b>Summary:</b> How would you describe the [% terms.bug %], in 
     approximately 60 or fewer characters?<br>
      A good summary should <b>quickly and uniquely identify [% terms.abug %]
-    report</b>. If an engineer can't identify your
-    [% terms.bug %] by its summary, it may be ignored when skimming through a
-    10-page list.<br>
-    <br>
-     A useful summary is "<tt>Cancelling a File Copy dialog crashes Nautilus</tt>".
-     Examples of bad summaries would be "<tt>Software crashes</tt>" or "<tt>copy problem</tt>".<br>
-    <br>
-     <b>Description:</b><br>
-     Provide a detailed problem report. [% terms.aBug %]'s recipients usually
-     expect the following information:</p>
+    report</b>. It should explain the problem, not your suggested solution.<br>
+    <ul>
+     <li>Good: "<tt>Cancelling a File Copy dialog crashes 
+     File Manager</tt>"</li>
+     <li>Bad: "<tt>Software crashes</tt>"</li>
+     <li>Bad: "<tt>Browser should work with my web site</tt>"</li>
+    </ul>
+    
+    <b>Description:</b>
+    The details of your problem report, including:</p>
 
     <blockquote>
-      <p><b>Overview Description:</b> More detailed restatement of
+      <p><b>Overview:</b> More detailed restatement of
       summary.</p>
 
       <blockquote>
 <pre>
-Drag-selecting any page crashes Mac builds in NSGetFactory
+Drag-selecting any page crashes Mac builds in the NSGetFactory function.
 </pre>
       </blockquote>
 
@@ -189,7 +111,8 @@ Drag-selecting any page crashes Mac builds in NSGetFactory
 
       <blockquote>
 <pre>
-1) View any web page. (I used the default sample page, resource:/res/samples/test0.html)
+1) View any web page. (I used the default sample page, 
+resource:/res/samples/test0.html)
 
 2) Drag-select the page. (Specifically, while holding down 
 the mouse button, drag the mouse pointer downwards from any 
@@ -232,116 +155,28 @@ Build 2006-08-10 on Mac OS 10.4.3
 
       <blockquote>
 <pre>
-- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
+Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
 </pre>
       </blockquote>
 
-      <p><b>Additional Information:</b> Any other debugging information.
-      For crashing [% terms.bugs %]:</p>
+      <p><b>Additional Information:</b> Any other useful information.
+      <br><br>For crashing [% terms.bugs %]:</p>
 
       <ul>
         <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>
 
-        <li><b>Mac OS X:</b> Attach the "Crash Reporter" log that appears upon crash.
-        Only include the section directly below the crashing thread, usually titled
-        "Thread 0 Crashed". Please do not paste the entire log!</li>
-
+        <li><b>Mac OS X:</b> Attach the "Crash Reporter" log that appears
+        upon crash.
+        Only include the section directly below the crashing thread, usually 
+        titled "Thread 0 Crashed". Please do not paste the entire log!</li>
       </ul>
-
     </blockquote>
 
-  <p>You're done!<br>
-  <br>
-   After double-checking your entries for any possible errors, press the
-  "Commit" button. Your [% terms.bug %] report will now be in 
+  <p>Double-check your report for errors and omissions, then press "Commit".
+  Your [% terms.bug %] report will now be in 
   the [% terms.Bugzilla %] database.<br>
   </p>
 </blockquote>
-<hr>
-
-<h3><a name="more">More Information on Writing Good [% terms.Bugs %]</a></h3>
-
-<blockquote>
-  <p><b><a name="tips"></a> 1. General Tips for a Useful [% terms.Bug %] 
-     Report</b></p>
-
-  <blockquote>
-    <p><b>Use an explicit structure, so your [% terms.bug %] reports are easy
-    to skim.</b> [% terms.Bug %] report users often need immediate access to 
-    specific sections of your [% terms.bug %]. Follow the structure 
-    recommended above.</p>
-
-    <p><b>Avoid cuteness if it costs clarity.</b> Nobody will be laughing
-    at your funny [% terms.bug %] title at 3:00 AM when they can't remember how 
-    to find your [% terms.bug %].</p>
-
-    <p><b>One [% terms.bug %] per report.</b> Completely different people 
-    typically fix, verify, and prioritize different [% terms.bugs %]. If you 
-    mix a handful of [% terms.bugs %] into a single report, the right people 
-    probably won't discover your [% terms.bugs %] in a timely fashion, if at 
-    all. Certain [% terms.bugs %] are also more important than others. It's 
-    impossible to prioritize [% terms.abug %] report when
-    it contains four different issues, all of differing importance.</p>
-
-    <p><b>No [% terms.bug %] is too trivial to report.</b> Unless you're 
-    reading the source code, you can't see actual software [% terms.bugs %], 
-    like a dangling pointer -- you'll see their visible manifestations, such 
-    as the segfault when the application finally crashes. Severe software 
-    problems can manifest themselves in superficially trivial ways. File them
-    anyway.<br>
-    </p>
-  </blockquote>
-
-  <p><b><a name="summary"></a>2. How and Why to Write Good [% terms.Bug %]
-  Summaries</b></p>
-
-  <blockquote>
-    <p><b>You want to make a good first impression on the [% terms.bug %]
-    recipient.</b> Just like a New York Times headline guides readers
-    towards a relevant article from dozens of choices, will 
-    your [% terms.bug %] summary suggest that your [% terms.bug %] report is 
-    worth reading from dozens or hundreds of choices?</p>
-
-    <p>Conversely, a vague [% terms.bug %] summary like <tt>install 
-    problem</tt> forces anyone reviewing installation [% terms.bugs %] to waste 
-    time opening up your [% terms.bug %] to determine whether it matters.</p>
-
-    <p><b>Your [% terms.bug %] will often be searched by its summary.</b> Just 
-    as you'd find web pages with Google by searching with keywords, so will other
-    people locate your [% terms.bugs %]. Descriptive [% terms.bug %] summaries are
-    naturally keyword-rich and easier to find.</p>
-
-    <p>For example, you'll find [% terms.abug %] titled "<tt>Dragging icons 
-    from List View to gnome-terminal doesn't paste path</tt>" if you search on
-    "List", "terminal", or "path". Those search keywords wouldn't have
-    found [% terms.abug %] titled "<tt>Dragging icons doesn't paste</tt>".</p>
-
-    <p>Ask yourself, "Would someone understand my [% terms.bug %] from just 
-    this summary?" If so, you've succeeded.</p>
-
-    <p><b>Don't write titles like these:</b></p>
-
-    <ol>
-      <li>"Can't install" - Why can't you install? What happens when you
-      try to install?</li>
-
-      <li>"Severe Performance Problems" - ...and they occur when you do
-      what?</li>
-
-      <li>"back button does not work" - Ever? At all?</li>
-    </ol>
-
-    <p><b>Good [% terms.bug %] titles:</b></p>
-
-    <ol>
-      <li>"Save button disabled after failed post attempt" -
-      Explains the problem and context.</li>
-
-      <li>"Enter &amp; Escape have no effect in 'Upload Photos' dialog" -
-      Also explains the problem and context.</li>
-    </ol>
-  </blockquote>
-</blockquote>
 
 [% INCLUDE global/footer.html.tmpl %]