improve query system documentation

src/queries/incremental-compilation-in-detail.md

@@ -186,7 +186,9 @@ By using red-green marking we can avoid the devastating cumulative effect of
 having false positives during change detection. Whenever a query is executed
 in incremental mode, we first check if its already green. If not, we run
 `try_mark_green()` on it. If it still isn't green after that, then we actually
-invoke the query provider to re-compute the result.
+invoke the query provider to re-compute the result. Re-computing the compute might 
+then itself involve recursively invoking more queries, which can mean we come back
+to the `try_mark_green()` algorithm for the dependencies recursively.
 
 
 ## The Real World: How Persistence Makes Everything Complicated

src/queries/incremental-compilation.md

@@ -21,6 +21,20 @@ not a general graph).
 
 [DAG]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
 
+> **NOTE**: You might think of a query as simply the definition of a query.
+> A thing that you can invoke, a bit like a function, 
+> and which either returns a cached result or actually executes the code.
+> 
+> If that's the way you think about queries,
+> it's good to know that in the following text, queries will be said to have colours. 
+> Keep in mind though, that here the word query also refers to a certain invocation of 
+> the query for a certain input. As you will read later, queries are fingerprinted based 
+> on their arguments. The result of a query might change when we give it one argument 
+> and be coloured red, while it stays the same for another argument and is thus green.
+> 
+> In short, the word query is here not just used to mean the definition of a query, 
+> but also for a specific instance of that query with given arguments.
+
 On the next run of the compiler, then, we can sometimes reuse these
 query results to avoid re-executing a query. We do this by assigning
 every query a **color**:

src/queries/query-evaluation-model-in-detail.md

@@ -174,9 +174,9 @@ Since query providers are regular functions, this would behave much as expected:
 Evaluation would get stuck in an infinite recursion. A query like this would not
 be very useful either. However, sometimes certain kinds of invalid user input
 can result in queries being called in a cyclic way. The query engine includes
-a check for cyclic invocations and, because cycles are an irrecoverable error,
-will abort execution with a "cycle error" messages that tries to be human
-readable.
+a check for cyclic invocations of queries with the same input aguments. 
+And, because cycles are an irrecoverable error, will abort execution with a 
+"cycle error" message that tries to be human readable.
 
 At some point the compiler had a notion of "cycle recovery", that is, one could
 "try" to execute a query and if it ended up causing a cycle, proceed in some