281185 - Add boolean charts docs

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement, P2)

Description

[Joel Peshkin]

Comment 1

[Joel Peshkin]

Attachment: Patch to explain boolean charts

Comment 2

[Joel Peshkin]

Attachment: Revised docs patch

A little clearer -- thanks to Colin

Comment 3

[Shane H. W. Travis]

Comment on attachment 173545 [details] [diff] [review]
Revised docs patch

Setting review request to [e-mail] so it shows up in the
docs review queue

Comment 4

[Shane H. W. Travis]

Comment on attachment 173545 [details] [diff] [review]
Revised docs patch

General comment: for all docs patches I've done, I have been layering (almost)
all tags with a two-space indent. I notice that you do it for <section> and
<blockquote>, but you do not do it for <para>. (You also don't do it for
<title> but I don't either, as that's always a one-liner.) I'd appreciate it if
you could keep the style consistent with how things are being done now.

General Comment #2: I'm not sure that <blockquote> is the right way to do your
examples. You might want to try <example> ... but then again, there may be a
better way yet. I'm not an SGML guru at all.


+      returned by a query. It is possible to search for bugs on 
+      based on elaborate combinations of critera.</para>

"bugs on based on"

+      <para>The simplest boolean searches have only one term. These searches
+      permit the selected left <emphasis>field</emphasis>
+      to be compared using a
+      selectable <emphasis>operator</emphasis> to a
+      specified <emphasis>value.</emphasis>

I infer that you're using the <emphasis> tags to define terms that you'll use
later. I think you're too terse here, though, and the information doesn't come
through well because it's so compact. These three fields are critical to
boolean searching, and could do with a little more explanation... something
like:

-----
There are three fields in the Boolean Search section of the Query page. Their
names and functions are described as follows:
  * Field - a picklist containing all the elements found on the search page,
	    plus some element+qualifier combinations. These are the items 
	    being searched by your boolean query.
  * Operator - a picklist containing the actions that can be performed on 
	    the items in the Field picklist.
  * Value - A text box into which you can enter the information needed by
	    your boolean query.

Not all of the field/operator combinations will make complete sense: trying to
create a boolean query containing 'Bug # | changed by' or 'Summary |
 is less than', for example, will produce confusing (or useless, or empty)
results. Furthermore, almost any query can be scuttled by putting garbage, or
even just incorrectly formatted text, into the Values field. Despite these
caveats, advanced Bugzilla users make good use of boolean searches because of
their flexibility and precision.
-----

Feel free to use any or all of the above; I did not verify it for factual
correctness, though, just FYI.
(Use <itemizedlist> and <listitem> to get a visual like the above text.)


+      Using the "And," "Or," and "Add Another Boolean Chart" buttons, 
+      additonal terms can be included in the query, further
+      altering the list of bugs returned by the query.</para>

In what way? How does 'And' differ from 'Add another boolean chart'? It's
obvious to we programmers, but not so much to everyone else...

Also, here is where I would add your earlier clause, "The simplest boolean
searches have only one term."

+      <section id="pronouns">
+	 <title>Pronouns</title>
+	 <para>Sometimes, a query needs to compare a field containing
+	 a user's ID (such as the reporter) with another field containing
there is no 'reporter' option in Fields, only ReportedBy.

+	 a user's ID (such as the assignee). When the operator is either 
+	 "equals" or "notequals", the value can be "%reporter%", 
+	 "%assignee%", "%qacontact%", or "%user%."  The user pronoun
+	 behaves as the user who is executing the query or, in the case
+	 of whining reports, the user who will be the recipient
+	 of the report.</para>
+      </section>

Is 'pronouns' really what you mean here? It seems like you're talking about
substitutions.

How does the %reporter%/%qacontact%/%assignee% pronoun act? By bringing up the
behaviour of one, you make me question the behaviour of all.

Again, it seems like you're trying to conflate the existence of substitutable
keywords with the unique behaviour of one item in the set.


+	 However, the search 
+	 <blockquote>
+	   <para>("CC" "does not contain the string" "@mozilla.org")</para>
+	 </blockquote>
+	 would find every bug where anyone on the CC list did not contain 
+	 "@mozilla.org" while
+	 <blockquote>
+	   <para>NOT("CC" "contains the string" "@mozilla.org")</para>
+	 </blockquote>
+	 would find every bug where there was nobody on the CC list who
+	 did contain the string. 


I know that negation-logic is a head-scratcher at the best of times... but
these two sentences are incredibly dense informationally, and not likely to
make much sense to many laymen.


Similarly, the use of negation also permits
+	 complex expressions to be built using terms OR'd together and then
+	 negated. Negation permits queries such as
+	 <blockquote>
+	   <para>NOT(("product" "equals" "update") OR 
+	   ("component" "equals" "Documentation"))</para>
+	 </blockquote>
+	 to find bugs that are neither 
+	 in the update product or in the documentation component 

IMHO, most people are going to have a much easier time understanding:
  product | is not equal | update AND product | is not equal | documentation
than
  NOT (product | is equal | update OR product | is equal | documentation )
because the switching of the AND to OR is not an intuitive step unless you have
studied boolean algebra. Since this query can be performed in a simpler and
more intuitive way, is it a good idea to include it as an example for why 'NOT'
is useful?


+	 <blockquote>
+	   <para>NOT(("commenter" "equals" "%assignee%") OR 
+	   ("component" "equals" "Documentation"))</para>
+	 </blockquote>
+	 to find non-documentation
+	 bugs on which the assignee has never commented.</para>

This, on the other hand, is a much better example, because (if I understand the
search correctly) reversing this example as above ( to read
"commenter|!=|assignee AND component| != | documentation" ) would not have the
same effect; it would find all documentation bugs where at least one commenter
is not the %assignee%, which would probably be all of them... including ones
where the %assignee% had commented, because surely someone else commented too.
(Right?) If so, you should use this example, and expand on it to show this
difference between the two types of negation.

Comment 5

[Joel Peshkin]

Attachment: revised again

I resolved the formatting items and added some of Travis's verbiage.

I am sure that, on a subsequent bug, someone will continue to refine the
descriptions of the boolean logic.  However, since there is currently no
documentation on the boolean charts at all, I think this should go in and get
tuned further as we go forward.

Comment 6

[Colin Ogilvie [:cso]]

Comment on attachment 174572 [details] [diff] [review]
revised again

Setting Review to Docs so it appears on its queue.

Comment 7

[Joel Peshkin]

Attachment: HTML page compiled from attachment 174572

Comment 8

[Colin Ogilvie [:cso]]

Comment on attachment 174572 [details] [diff] [review]
revised again

Travis asked me to check this compiled to the docs and then r+ it.

Comment 9

[Joel Peshkin]

checked in.

I'm sure there is plenty of room for improvment.  Feel free.