 (defcard-doc
   "### Using links
 
-  Links look like idents, but they replace the ID portion with the special symbol `_`. Note
-  that symbols need to be quoted, so a query including a link will need to leverage
+  Links look like idents, but they replace the ID portion with the special symbol `_`.
+  One way of thinking about this is, go get `:my-key`, which is at the top level, and
+  `_` implies that you don't care about the id. This is very similar to the ident based
+  query above, except that in the ident query, you do care about the id (the 2nd tuple value).
+  This pattern of `[[:first :second]]` is a lot like saying, `(get-in app-db [:first :second])`
+  Furthemore, `[{[:first :second] [:prop-a :prop-b]]}]` is like
+  `(-> app-db (get-in [:first :second]) (select-keys [:prop-a :prop-b]))`. Remember the constraint
+  about having two values in the ident? Well, the `_` allows us to use an *I'm not worried about the
+  second value*. This is a really powerful notion when you apply it to nested queries.
+
+  Note that symbols need to be quoted, so a query including a link will need to leverage
   quoting in normal syntax. In the section on the database format we talked about top-level
   singletons. Links are the way to access them anywhere from the UI because they can appear
   at any level in the nested query.

            [untangled-tutorial.queries.query-demo :as qd]
            [devcards.util.edn-renderer :refer [html-edn]]
            [devcards.core :as dc :refer-macros [defcard defcard-doc]]))

; TODO: pointers from ref guide
; TODO: Move query parameter stuff to server-side.
; TODO: Give some motivation about not using q params on client UI, with pointer to later section about post-mutations that solve
; the same problem.
; TODO: Mention that parameters on queries ARE useable and useful when talking to the server (mutations that modify the remote request).

(defcard-doc
  "


  ### Parameters in the query

  Untangled takes the approach to not use, or parse query parameters in the client for reads. Adding query param
  parsing introduces complexity in the parser, and you simply do not need it. In many cases, you will
  find that follow on reads from a mutation solve your problem with less complexity. However, in
  [server side interactions](http://untangled-web.github.io/untangled/tutorial.html#!/untangled_tutorial.H_Server_Interactions),
  you will find that query params can be used for reads. And since you will implement your own read parser,
  you have control of how those are dealt with. [Mutations](http://untangled-web.github.io/untangled/tutorial.html#!/untangled_tutorial.G_Mutation)
  are a place where parameters are very useful. Plan on using them there.

  ### Looking up by ident

