Cleanup queries.md (#41)

* Improve grammar
* Improve clock-vs-timestamp message
* Fix whitespace
* Add some explanations
* Move the clock-vs-timestamp message to the top of the sorting section
* Clarify wording more
* Fix my misconception

1 files changed, 12 insertions, 15 deletions

diff --git a/doc/queries.md b/doc/queries.md
index 27cfda21..93135070 100644
--- a/doc/queries.md
+++ b/doc/queries.md
@@ -1,6 +1,6 @@
 # Searching bugs
 
-You can search bugs using a micro query language for both filtering and sorting. A query could looks like this:
+You can search bugs using a micro query language for both filtering and sorting. A query could look like this:
 
 ```
 status:open sort:edit
@@ -8,9 +8,9 @@ status:open sort:edit
 
 A few tips:
 
-- query are case insensitive.
-- you can combine as much qualifier as you want.
-- you can use quotation for multi-word search term. For example, use `author:"René Descartes"` to search with a complete name.
+- queries are case insensitive.
+- you can combine as many qualifiers as you want.
+- you can use double quotes for multi-word search terms. For example, `author:"René Descartes"` searches for bugs opened by René Descartes, whereas `author:René Descartes` will throw an error since full-text search is not yet supported.
 
 
 ## Filtering
@@ -35,7 +35,7 @@ You can filter based on the person who opened the bug.
 
 ### Filtering by label
 
-You can filter based on bug's label.
+You can filter based on the bug's label.
 
 | Qualifier     | Example                                                                   |
 | ---           | ---                                                                       |
@@ -46,16 +46,17 @@ You can filter based on bug's label.
 
 You can filter bugs based on the absence of something.
 
-
 | Qualifier  | Example                                |
 | ---        | ---                                    |
 | `no:label` | `no:label` matches bugs with no labels |
 
 ## Sorting
 
-You can sort result by adding a `sort:` qualifier to your query.
+You can sort results by adding a `sort:` qualifier to your query. “Descending” means most recent time or largest ID first, whereas “Ascending” means oldest time or smallest ID first.
+
+Note: to deal with differently-set clocks on distributed computers, `git-bug` uses a logical clock internally rather than timestamps to order bug changes over time. That means that the timestamps recorded might not match the returned ordering. More on that in [the documentation](model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display)
 
-### Sort by Id 
+### Sort by Id
 
 | Qualifier                  | Example                                              |
 | ---                        | ---                                                  |
@@ -66,20 +67,16 @@ You can sort result by adding a `sort:` qualifier to your query.
 
 You can sort bugs by their creation time.
 
-Note: to deal with badly set clocks in a distributed system, `git-bug` use a logical clock internally rather than timestamp to order bugs edition over time. That means that the timestamps recorded might not match the returned ordering. More on that in [the documentation](model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display)
-
 | Qualifier                               | Example                                                            |
 | ---                                     | ---                                                                |
 | `sort:creation` or `sort:creation-desc` | `sor:creation` will sort bugs by their descending creation time    |
 | `sort:creation-asc`                     | `sor:creation-asc` will sort bugs by their ascending creation time |
 
-### Sort by Edition time
-
-You can sort bugs by their edition time.
+### Sort by Edit time
 
-Note: to deal with badly set clocks in a distributed system, `git-bug` use a logical clock internally rather than timestamp to order bugs edition over time. That means that the timestamps recorded might not match the returned ordering. More on that in [the documentation](model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display)
+You can sort bugs by their edit time.
 
 | Qualifier                       | Example                                                            |
 | ---                             | ---                                                                |
 | `sort:edit` or `sort:edit-desc` | `sor:edit` will sort bugs by their descending last edition time    |
-| `sort:edit-asc`                 | `sor:edit-asc` will sort bugs by their ascending last edition time |
\ No newline at end of file
+| `sort:edit-asc`                 | `sor:edit-asc` will sort bugs by their ascending last edition time |