. some preliminary corrections to the documentation

web/source/documentation/_category.html.md

@@ -110,9 +110,9 @@ Pretty straightforward, right?
 
 ### Option weight{#indexes-categories-weight}
 
-The weight option defines how strongly a word is weighed. By default, Picky rates a word according to the logarithm of its occurrence. This means that a word that occurs more often will be slightly higher weighed.
+The weight option defines how strongly a word is weighed. By default, Picky rates a word according to the logarithm of its occurrence. This means that a word that occurs more often will be weighed slightly higher.
 
-You define this by this:
+You define a weight option like this:
 
     category :some, weight: MyWeights.new
 
@@ -122,11 +122,11 @@ You can also pass in your own weight generators. See [this article](http://flori
 
 If you don't want Picky to calculate weights for your indexed entries, you can use constant or dynamic weights.
 
-With 0.0 as default weight:
+With 0.0 as a constant weight:
 
     category :some, weight: Weights::Constant.new # Returns 0.0 for all results.
 
-With 3.14 as set weight:
+With 3.14 as a constant weight:
 
     category :some, weight: Weights::Constant.new(3.14) # Returns 3.14 for all results.
 
@@ -136,7 +136,7 @@ Or with a dynamically calculated weight:
       sym_or_str.length # Uses the length of the symbol as weight.
     end
 
-You almost never need to use your specific weights. More often than not, you can fiddle with [boosting combinations of categories](#search-options-boost) , via the `boost` method in searches.
+You almost never need to define weights. More often than not, you can fiddle with [boosting combinations of categories](#search-options-boost) , via the `boost` method in searches.
 
 #### Why choose fiddling with weight rather than boosts?
 
@@ -152,13 +152,15 @@ This adds +1 to all weights. Why the logarithmic? By default, Picky weighs categ
 
 The `Logarithmic` initializer accepts a constant to be added to the result. Adding the constant `+1` is like multiplying the weight by `Math::E` (e is Euler's constant). If you don't understand, don't worry, just know that by adding a constant you multiply by a certain value.
 
-In short: Use `weight` on the index, if you need a category to be boosted everywhere, wherever it occurs, and use [boosting](#search-options-boost) if you need to boost specific combinations of categories only for a specific search.
+In short:
+* Use `weight` on the index, if you need a category to be boosted everywhere, wherever it occurs
+* Use [boosting](#search-options-boost) if you need to boost specific combinations of categories only for a specific search.
 
 ### Option similarity{#indexes-categories-similarity}
 
 The similarity option defines if a word is also found when it is typed wrong, or _close_ to another word. So, "Picky" might be already found when typing "Pocky~" (Picky will search for similar word when you use the tilde, ~).
 
-You define this by this:
+You define a similarity option like this:
 
     category :some, similarity: Similarity::None.new
 
@@ -176,7 +178,7 @@ You can also pass in your own similarity generators. See [this article](http://f
 
 Usually, when you search for `title:wizard` you will only find books with "wizard" in their title.
 
-Maybe your client would like to be able to only enter "t"wizard"". In that case you would use this option:
+Maybe your client would like to be able to only enter `t:wizard`. In that case you would use this option:
 
     category :some, qualifier: "t"
 
@@ -225,7 +227,7 @@ You can also populate the index at runtime (eg. with `index.add`) using a lambda
 
 ### Option key_format{#indexes-categories-keyformat}
 
-You almost never use this, as the key format will usually be the same for all categories, which is when you would define it on the index, [like so](#indexes-keyformat).
+You will almost never need to use this, as the key format will usually be the same for all categories, which is when you would define it on the index, [like so](#indexes-keyformat).
 
 But if you need to, use as with the index.
 
@@ -236,7 +238,7 @@ But if you need to, use as with the index.
 
 ### Option source{#indexes-categories-source}
 
-You almost never use this, as the source will usually be the same for all categories, which is when you would define it on the index, "like so":#indexes-sources.
+You will almost never need to use this, as the source will usually be the same for all categories, which is when you would define it on the index, "like so":#indexes-sources.
 
 But if you need to, use as with the index.
 
@@ -263,7 +265,7 @@ And Person has a method `#names` which returns this array:
       
     end
 
-Then Picky will simply use the tokens in that array without (pre-)processing them. Of course, this means you need to really do all the tokenizing work. If you leave the tokens uppercase, then nothing will be found, unless you set the Search to be case-sensitive, for example.
+Then Picky will simply use the tokens in that array without (pre-)processing them. Of course, this means you need to do all the tokenizing work. If you leave the tokens in uppercase formatting, then nothing will be found, unless you set the Search to be case-sensitive, for example.
 
 ### User Search Options{#indexes-categories-searching}
 
@@ -276,11 +278,11 @@ Users can use some special features when searching. They are:
 * Multi-categorized: `title,author:something` (Picky will search in title _and_ author categories, in each index of the search)
 * Range: `year:1999-2012` (Picky will search all values in a Ruby `Range`: `(1999..2012)`)
 
-These options can be combined (e.g. `title,author:funky~"`): This will try to find similar words to funky (like "fonky"), but no partials of them (like "fonk"), in both title and author. 
+These options can be combined (e.g. `title,author:funky~"`): This will try to find similar words to funky (like "fonky"), but no partials of them (like "fonk"), in both title and author.
 
 Non-partial will win over partial, if you use both, as in `test*"`.
 
-Also note that these options need to make it through the [tokenizing](#tokenizing), so don't remove any of `*":,-`.
+Also note that these options need to make it through the [tokenizing](#tokenizing), so don't remove any of `*":,-`. TODO unclear
 
 ### Key Format (Format of the indexed Ids){#indexes-keyformat}
 
@@ -311,4 +313,4 @@ This index is identified by `media` in the results:
       result_identifier 'media'
     end
 
-You still refer to it as `:books` in e.g. Rake tasks, `Picky::Indexes[:books].reload`. It's just for the results.
+You still refer to it as `:books` in e.g. Rake tasks, `Picky::Indexes[:books].reload`. The `result_identifier` option is just for the results.

web/source/documentation/_facets.html.md

@@ -9,7 +9,7 @@ In Picky, categories are explicit slices over your index data. Picky facets are
 
 What does "implicit" mean here?
 
-It means that you didn't explicitly say, "My data is shoes, and I have these four brands: Nike, Adidas, Puma, and Vibram". 
+It means that you didn't explicitly say, "My data is shoes, and I have these four brands: Nike, Adidas, Puma, and Vibram".
 
 No, instead you told Picky that your data is shoes, and there is a category "brand". Let's make this simple:
 
@@ -29,11 +29,11 @@ With this data in mind, let's look at the possibilities:
 
 Index facets are very straightforward.
 
-You ask the index for facets and it will give you all the facets it has and how many:
+You ask the index for facets and it will give you all the facets it has and how many results there are within:
 
     index.facets :brand # => { 'nike' => 2, 'adidas' => 1 }
 
-The category type is a good candidate also:
+The category type is a good candidate for facets, too:
 
     index.facets :type # => { 'sports' => 2, 'casual' => 1 }
 
@@ -43,30 +43,30 @@ What are the options?
 * `counts`: `index.facets :brand, counts: false # => ['nike', 'adidas']`
 * both options: `index.facets :brand, at_least: 2, counts: false # => ['nike']`
 
-`at_least` only gives you facets which occur at least n times and `counts` tells the facets method whether you want the counts with the facets or not.
+`at_least` only gives you facets which occur at least n times and `counts` tells the facets method whether you want counts with the facets or not. If counts are omitted, you'll get an `Array` of facets instead of a `Hash`.
 
 Pretty straightforward, right?
 
 Search facets are quite similar:
 
 ### Search facets
 
-Search facets work the exact same way as index facets and you can use them in the same way:
+Search facets work similarly to index facets. In fact, you can use them in the same way:
 
     search_interface.facets :brand # => { 'nike' => 2, 'adidas' => 1 }
     search_interface.facets :type # => { 'sports' => 2, 'casual' => 1 }
     search_interface.facets :brand, at_least: 2 # => { 'nike' => 2 }
     search_interface.facets :brand, counts: false # => ['nike', 'adidas']
     search_interface.facets :brand, at_least: 2, counts: false # => ['nike']
 
-However, you can also filter the facets with a filter query option.
+However search facets are more powerful, as you can also filter the facets with a filter query option:
 
     shoes.facets :brand, filter: 'some filter query'
 
 What does that mean?
 
 Usually you want to use multiple facets in your interface.
-For example, a customer might already have filtered by type "sports" because they are only interested in sports shoes.
+For example, a customer might already have filtered results by type "sports" because they are only interested in sports shoes.
 Now you'd like to show them the remaining brands, so that they can filter on the remaining facets.
 
 How do you do this?
@@ -75,17 +75,17 @@ Let's say we have an index as above, and a search interface to the index:
 
     shoes = Picky::Search.new index
 
-Now, if the customer has already filtered for sports, you simply add the `filter` option:
+If the customer has already filtered for sports, you simply pass the query to the `filter` option:
 
     shoes.facets :brand, filter: 'type:sports' # => { 'nike' => 1, 'adidas' => 1 }
 
 This will give you only 1 "nike" facet. If the customer filtered for "casual":
 
     shoes.facets :brand, filter: 'type:casual' # => { 'nike' => 1 }
 
-then we'd only get the casual nike facet (from that one "barefoot" shoe).
+then we'd only get the casual nike facet (from that one "barefoot" shoe picky loves so much).
 
-If the customer has filtered for brand "nike" and type "sports", you'd get:
+As said, filtering works like the query string passed to picky. So if the customer has filtered for brand "nike" and type "sports", you'd get:
 
     shoes.facets :brand, filter: 'brand:nike type:sports' # => { 'nike' => 1 }
     shoes.facets :name, filter: 'brand:nike type:sports' # => { 'zoom' => 1 }
@@ -112,7 +112,7 @@ This is how you test facets:
 
 #### Index Facets
 
-    # We should find two surname facets. 
+    # We should find two surname facets.
     #
     index.facets(:surname).should == {
       'hanke' => 2,  # hanke occurs twice
@@ -153,9 +153,9 @@ This is how you test facets:
 Two rules:
 
 1. Index facets are faster than filtered search facets. If you don't filter though, search facets are as fast as index facets.
-1. Only use facets on data which are a good fit for facets – where there aren't many facets to the data.
+2. Only use facets on data which are a good fit for facets – where there aren't many facets to the data.
 
-A good example for a good fit would be brands of shoes.
+A good example for a meaningful use of facets would be brands of shoes.
 There aren't many different brands (usually less than 100).
 
 So this facet query

web/source/documentation/_generators.html.md

@@ -3,9 +3,9 @@
 {.edit}
 [edit](http://github.com/floere/picky/blob/master/web/source/documentation/_generators.html.md)
 
-Picky offers a few generators to have a running server and client up in 5 minutes. Please follow the [Getting Started](getting_started.html).
+Picky offers a few generators to have a running server and client up in 5 minutes. So you can either [get started right away](getting_started.html)
 
-Or, run gem install
+or, run gem install
 
     gem install picky-generators
 
@@ -15,38 +15,38 @@ and simply enter
 
 This will raise an `Picky::Generators::NotFoundException` and show you the possibilities.
 
-The "All In One" Client/Server is interesting for Heroku projects, as it is a bit complicated to set up two servers that interact with each other.
+The "All In One" Client/Server might be interesting for Heroku projects, as it is a bit complicated to set up two servers that interact with each other.
 
 ### Servers{#generators-servers}
 
-Currently, Picky offers two generated example projects that you can adapt to your project: *Separate Client and Server* (suggested) and *All In One*.
+Currently, Picky offers two generated example projects that you can adapt to your project: *Separate Client and Server* (recommended) and *All In One*.
 
-If this is your first time with Picky, we suggest to start out with these even if you have a project where you want to integrate Picky already.
+If this is your first time using Picky, we suggest to start out with these even if you have a project where you want to integrate Picky already.
 
 #### Sinatra{#generators-servers-sinatra}
 
-This server is generated with
+The server is generated with
 
     picky generate server target_directory
 
-and generates a full sinatra server that you can try immediately. Just follow the instructions.
+and generates a full Sinatra server that you can try immediately. Just follow the instructions.
 
 #### All In One{#generators-servers-allinone}
 
 All In One is actually a single Sinatra server containing the Server AND the client. This server is generated with
 
     picky generate all_in_one target_directory
 
-and generates a full Sinatra Picky server and client that you can try immediately. Just follow the instructions.
+and generates a full Sinatra Picky server and client in one that you can try immediately. Just follow the instructions.
 
 ### Clients{#generators-clients}
 
-Picky currently offers an example Sinatra client that you can adapt for your project (or look at it how to use in Rails).
+Picky currently offers an example Sinatra client that you can adapt to your project (or look at it to get a feeling for how to use Picky in Rails).
 
 #### Sinatra{#generators-clients-sinatra}
 
 This client is generated with
 
     picky generate client target_directory
 
-and generates a full Sinatra client (including Javascript etc.) that you can try immediately. Just follow the instructions.
+and generates a full Sinatra Picky client (including Javascript etc.) that you can try immediately. Just follow the instructions.

web/source/documentation/_index.html.md

@@ -54,7 +54,7 @@ Configuring an index:
 
 * [Configuration](#indexes-configuration)
 
-How does data get in there?
+How does data get into an index?
 
 * [Indexing](#indexes-indexing)
 * [Data Source Overview](#indexes-sources)

web/source/documentation/_indexes.html.md

@@ -47,7 +47,7 @@ The resulting ids should be from the same id space to be useful – or the ids s
 
 The in-memory index saves its indexes as files transparently in the form of JSON files that reside in the `/index` directory.
 
-When the server is started, they are loaded into memory. As soon as the server is stopped, the indexes are not in memory again.
+When the server is started, they are loaded into memory. As soon as the server is stopped, the indexes are deleted from memory.
 
 Indexing regenerates the JSON index files and can be reloaded into memory, even in the running server (see below).
 
@@ -57,7 +57,7 @@ The Redis index saves its indexes in the Redis server on the default port, using
 
 When the server is started, it connects to the Redis server and uses the indexes in the key-value store.
 
-Indexing regenerates the indexes in the Redis server – you do not have to restart the server for that.
+Indexing regenerates the indexes in the Redis server – you do not have to restart the server running Picky.
 
 #### SQLite{#indexes-types-sqlite}
 
@@ -87,7 +87,7 @@ To get a *single index* use
 
     Picky::Indexes[:index_name]
 
-and to get a *single category*, use
+and to get a *single category* of an index, use
 
     Picky::Indexes[:index_name][:category_name]
 
@@ -124,7 +124,7 @@ This is all you can do to configure an index:
       result_identifier 'boooookies'
     end
 
-Usually you don't need to configure all that.
+Usually you won't need to configure all that.
 
 But if your boss comes in the door and asks why X is not found… you know. And you can improve the search engine relatively *quickly and painless*.
 
@@ -148,12 +148,14 @@ You define them on an *index*:
       source { Book.all } # Loads on indexing. Preferred.
     end
 
-Or even a *single category*:
+Or even on a *single category*:
 
     Index.new :books do
       category :title,
                source: lambda { Book.all }
     end
+		
+TODO more explanation how index sources and single category sources might work together.
 
 Explicit data sources must [respond to #each](#indexes-sources-each), for example, an Array.
 
@@ -204,7 +206,7 @@ For example, this would instantly get the records, since `#all` is a kicker meth
       source Book.all # Not the best idea.
     end
 
-In this case, you can give the `source` method a block:
+In this case, it is better to give the `source` method a block:
 
     Index::Memory.new :books do
       source { Book.all }
@@ -235,8 +237,8 @@ Or to a specific category:
 Currently, there are 7 methods to change an index:
 
 * `#add`: Adds the thing to the end of the index (even if already there). `index.add thing`
-* `#<<`: Adds the thing to the end of the index (shows up last in sorting). `index << thing`
-* `#unshift`: Adds the thing to the beginning of the index (shows up first in sorting). `index.unshift thing`
+* `#<<`: Adds the thing to the end of the index (shows up last in results). `index << thing`
+* `#unshift`: Adds the thing to the beginning of the index (shows up first in results). `index.unshift thing`
 * `#remove`: Removes the thing from the index (if there). `index.remove thing`
 * `#replace`: Replaces the thing in the index (if there, otherwise like `#add`). Equal to `#remove` followed by `#add`. `index.replace thing`
 * `#replace_from`: Pass in a Hash. Replaces the thing in the index (if there, otherwise like `#add`). Equal to `#remove` followed by `#add`. `index.replace id: 1, example: "Hello, I am Hash!"`