Created attachment 173472 [details] [diff] [review] Patch to explain boolean charts
Attachment #173472 - Flags: review?(justdave)
Status: NEW → ASSIGNED
Priority: -- → P2
Target Milestone: --- → Bugzilla 2.20
Attachment #173472 - Flags: review?(justdave) → review?
Created attachment 173545 [details] [diff] [review] Revised docs patch A little clearer -- thanks to Colin
Comment on attachment 173545 [details] [diff] [review] Revised docs patch Setting review request to firstname.lastname@example.org so it shows up in the docs review queue
Attachment #173545 - Flags: review? → review?(documentation)
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.
Attachment #173545 - Flags: review?(documentation) → review-
Created attachment 174572 [details] [diff] [review] 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 on attachment 174572 [details] [diff] [review] revised again Setting Review to Docs so it appears on its queue.
Attachment #174572 - Flags: review? → review?(documentation)
Created attachment 174596 [details] HTML page compiled from attachment 174572 [details] [diff] [review]
Comment on attachment 174572 [details] [diff] [review] revised again Travis asked me to check this compiled to the docs and then r+ it.
Attachment #174572 - Flags: review?(documentation) → review+
checked in. I'm sure there is plenty of room for improvment. Feel free.
Status: ASSIGNED → RESOLVED
Last Resolved: 13 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.