Update documentation

README.md

@@ -10,7 +10,7 @@ An attempt to add stable support for Fulltext Search engines like Sphinx and Sol
 
 ## Requirements
 
-* SilverStripe 2.4. Untested in 3, but probably won't work.
+* SilverStripe 3.0
 
 ## Documentation
 
@@ -18,7 +18,7 @@ See docs/README.md
 
 ## TODO
 
-* Get rid of includeSubclasses - isn't actually used in practise, makes the codebase uglier, and ClassHierarchy can be
+* Get rid of includeSubclasses - isn't actually used in practice, makes the codebase uglier, and ClassHierarchy can be
 used at query time for most of the same use cases
 
 * Fix field referencing in queries. Should be able to do `$query->search('Text', 'Content')`, not

docs/README.md

@@ -2,19 +2,21 @@
 
 # FullTextSearch module
 
+An attempt to add stable support for Fulltext Search engines like Sphinx and Solr to SilverStripe CMS
+
 ## Maintainer Contact
 
 * Hamish Friedlander <hamish (at) silverstripe (dot) com>
 
 ## Requirements
 
-* SilverStripe 2.4. Untested in 3 alpha, but probably won't work.
+* SilverStripe 3.0
 
 ## Introduction
 
 This is a module aimed at adding support for standalone fulltext search engines to SilverStripe.
 
-It contains several layers.
+It contains several layers:
 
 * A fulltext API, ignoring the actual provision of fulltext searching
 
@@ -32,22 +34,23 @@ fulltext searching as an extension of the object model. However the disconnect b
 design and the object model meant that searching was inefficient. The abstraction would also often break and it was
 hard to then figure out what was going on.
 
-Instead this module provides the ability to define those indexes and queries in PHP. The indexes are defined as a mapping
-between the object model and the index model. This module then interogates model metadata to build the specific index
-definition. It also hooks into Sapphire in order to update the indexes when the models change.
+This module instead provides the ability to define those indexes and queries in PHP. The indexes are defined as a mapping
+between the SilverStripe object model and the connector-specific fulltext engine index model. This module then interrogates model metadata 
+to build the specific index definition. 
 
-Connectors then convert those index and query definitions into fulltext engine specific code.
+It also hooks into Sapphire in order to update the indexes when the models change and connectors then convert those index and query definitions 
+into fulltext engine specific code.
 
 The intent of this module is not to make changing fulltext search engines seamless. Where possible this module provides
 common interfaces to fulltext engine functionality, abstracting out common behaviour. However, each connector also
-offers it's own extensions, and there is some behaviour (such as getting the fulltext search engines installed, configured
-and running) that each connector deals with itself, in a way best suited to the specific fulltext search engines design.
+offers its own extensions, and there is some behaviour (such as getting the fulltext search engines installed, configured
+and running) that each connector deals with itself, in a way best suited to that search engine's design.
 
 ## Basic usage
 
-Basic usage is a four step process
+Basic usage is a four step process:
 
-1) Define an index (Note the specific connector index instance - that's what defines which engine gets used)
+1). Define an index in SilverStripe (Note: The specific connector index instance - that's what defines which engine gets used)
 
 ```php
 mysite/code/MyIndex.php:
@@ -62,24 +65,24 @@ class MyIndex extends SolrIndex {
 }
 ```
 
-2) Add something to the index (adding existing objects to the index is connector specific)
+2). Add something to the index (Note: You can also just update an existing document in the CMS. but adding _existing_ objects to the index is connector specific)
 
 ```php
 $page = new Page(array('Contents' => 'Help me. My house is on fire. This is less than optimal.'));
 $page->write();
 ```
 
-3) Build a query
+3). Build a query
 
 ```php
 $query = new SearchQuery();
 $query->search('My house is on fire');
 ```
 
-4) Apply that query to an index
+4). Apply that query to an index
 
 ```php
-singleton('MyIndex')->search($query);
+$results = singleton($index)->search($query);
 ```
 
 Note that for most connectors, changes won't be searchable until _after_ the request that triggered the change.

docs/Solr.md

@@ -1,12 +1,14 @@
-# Solr connector for SilverStripe fulltextsearch
+# Solr connector for SilverStripe fulltextsearch module
 
 This module provides a fulltextsearch module connector to Solr.
 
 It works with Solr in multi-core mode. It needs to be able to update Solr configuration files, and has modes for
 doing this by direct file access (when Solr shares a server with SilverStripe) and by WebDAV (when it's on a different server).
 
-Since Solr is Java based, this module requires a Java runtime to be present on the server Solr is running on (not nessecarily
-the same server the SilverStripe server is on).
+Since Solr is Java based, this module requires a Java runtime to be present on the server Solr is running on (not necessarily
+the same physical machine the SilverStripe server is on).
+
+* See the helpful [Solr Tutorial](http://lucene.apache.org/solr/api/doc-files/tutorial.html), for more on cores and querying.
 
 ## Getting started quickly (dev mode)
 
@@ -41,18 +43,25 @@ class MyIndex extends SolrIndex {
 }
 ```
 
-Open a terminal, change to thirdparty/solr/server and start Solr by running `java -jar start.jar`
+* Open a terminal, change to thirdparty/solr/server and start Solr by running `java -jar start.jar`
+* In another terminal run the configure task `sake dev/tasks/Solr_configure`
+* Then run the configure task `sake dev/tasks/Solr_reindex`
 
-In another terminal run the configure task `sake dev/tasks/Solr_configure`
+You can now visit http://localhost:8983/solr/MyIndex/admin/ to search the contents of the now created Solr index via the native SOLR UI
 
-Tne run the configure task `sake dev/tasks/Solr_reindex`
+## Debugging
 
-You can now visit http://localhost:8983/solr/MyIndex/admin/ to search the contents of the now created Solr index
+It is possible to manually replicate the data automatically sent to Solr when saving/publishing in SilverStripe, 
+which is useful when debugging front-end queries, see: thirdparty/solr/server/silverstripe-solr-test.xml but roughly:
+
+```
+#> java -Durl=http://localhost:8983/solr/MyIndex/update/ -Dtype=text/xml -jar post.jar silverstripe-solr-test.xml
+```
 
 -----
 
-These instructions will get you running quickly, but the Solr indexes will be stored in your project. You can also
-copy the thirdparty/solr directory somewhere else. The instructions are above still apply then - just set the path value
-in mysite/_config.php to point to this other location, and of course run `java -jar start.jar` from the new directory
+These instructions will get you running quickly, but the Solr indexes will be stored as binary files inside your SilverStripe project. You can also
+copy the thirdparty/solr directory somewhere else. The instructions above will still apply - just set the path value
+in mysite/_config.php to point to this other location, and of course run `java -jar start.jar` from the new directory,
 not the thirdparty one.