[docs][s]: improve documentation index page.

* lists of dependencies
* an overview of model and views

index.html

@@ -58,7 +58,7 @@
   <div class="content">
     <div class="page-header">
       <h1>
-        Recline Data Explorer <small>Data explorer and refinery all in pure Javascript</small>
+        Recline Data Explorer <small>Data explorer library and app all in pure Javascript</small>
       </h1>
     </div>
     <h4>Recline combines a data grid, Google Refine-style data transforms
@@ -68,31 +68,81 @@
 
     <h2 id="features">Main Features</h2>
     <ul>
-      <li>Open-source (and heavy reuser of existing open-source libraries like
+      <li>View and edit your data in a clean grid / table interface</li>
-      Backbone)</li>
-      <li>Pure javascript (no Flash) and designed for integration -- so it is
-      easy to embed in other sites and applications</li>
-      <li>View and edit your data in a clean grid interface</li>
       <li>Bulk update/clean your data using an easy scripting UI</li>
       <li>Easily extensible with new Backends so you can connect to your
       database or storage layer</li>
       <li>Visualize data</li>
+      <li>Pure javascript (no Flash) and designed for integration -- so it is
+      easy to embed in other sites and applications</li>
+      <li>Open-source</li>
+      <li>Built on <a
+        href="http://documentcloud.github.com/backbone/">Backbone</a> - so
+      robust design and extremely easy to exend</li>
+      <li>Properly designed model with clean separation of data and presentation</li>
+      <li>Componentized design means you use only what you need</li>
     </ul>
 
     <h2 id="demo">Demo</h2>
-    <ul>
+    <p><a href="demo/index.html" class="btn">Demo &raquo;</a></p>
-      <li><a href="demo/index.html">Demo</a></li>
-    </ul>
 
     <h2 id="downloads">Downloads & Dependencies <small>(Right-click, and use 'Save As')</small></h2>
-    <p><a href="recline.js" class="btn">Development Version (v0.2)</a></p>
+    <p><a href="recline.js" class="btn">Recline Current Version (v0.2) &raquo;</a></p>
+    <h3>Dependencies</h3>
+    <p>Javascript Libraries:</p>
+    <ul>
+      <li>Jquery >= 1.6</li>
+      <li>Underscore and Backbone (0.5.1)</li>
+      <li>JQuery Mustache</li>
+      <li>(Optional) JQuery Flot - for graphing</li>
+    </ul>
+    <p><strong>CSS</strong>: the demo utilizes bootstrap but you can integrate with your own HTML and CSS. Data Explorer specific CSS can be found here in the repo: <a href="https://github.com/okfn/recline/tree/master/css">https://github.com/okfn/recline/tree/master/css</a>.</p>
 
     <h2 id="using">Using It</h2>
-    <p>Check out the the <a href="demo/">Demo</a> and view source. The
+    <pre>
-    javascript you  want for actual integration is in: <a
+// Note: you should have included the relevant JS libraries (and CSS)
-      href="demo/js/app.js">app.js</a>.</p>
+// See above for dependencies
 
-    <h2 id="docs">Docs</h2>
+// Dataset is a Backbone model
+var dataset = recline.Model.Dataset({
+  id: 'my-id'
+  backend: {
+    // backend ID so we can look backend up in the registry  (see below)
+    type: 'memory'
+    // other backend config (e.g. API url with which to communicate)
+    // this will usually be backend specific
+    ...
+  }
+});
+// DataExplorer is a Backbone View
+var explorer = recline.View.DataExplorer({
+  model: dataset,
+  // you can specify any element to bind to in the dom
+  el: $('.data-explorer-here')
+});
+// Start Backbone routing (if you want routing support)
+Backbone.history.start();
+    </pre>
+    <p>More details and examples: see docs below and the <a
+      href="demo/">Demo</a> (hit view source). The javascript you  want for
+    actual integration is in: <a href="demo/js/app.js">app.js</a>.</p>
+
+    <h2 id="docs">Documentation</h2>
+    <p>Recline has a simple structure layered on top of the basic Model/View
+    distinction inherent in Backbone. There are the following three domain objects (all Backbone Models):</p>
+    <ul>
+      <li>Dataset: represents the dataset. Holds dataset info and a pointer to list of data items (Documents in our terminology) which it can load from the relevant Backend.</li>
+      <li>Document: an individual data item (e.g. a row from a relational database or a spreadsheet, a document from from a document DB like CouchDB or MongoDB).</li>
+      <li>Backend: provides a way to get data from a specific 'Backend' data source. They provide methods for loading and saving Datasets and individuals Documents as well as for bulk loading via a query API and doing bulk transforms on the backend</li>
+    </ul>
+    <p>There are then various Views (you can easily write your own). Each view holds a pointer to a Dataset:</p>
+    <ul>
+      <li>DataExplorer: the parent view which manages the overall app and sets up sub views.</li>
+      <li>DataTable: the data grid / table view.</li>
+      <li>FlotGraph: a simple graphing view using <a href="http://code.google.com/p/flot/">Flot</a>.</li>
+    </ul>
+
+    <h3>Source</h3>
     <ul>
       <li><a href="docs/model.html">Models</a></li>
       <li><a href="docs/backend.html">Backends</a></li>
@@ -117,7 +167,7 @@
       href="https://github.com/maxogden/recline">Max's original recline
       codebase</a> combining some portions of the <a
       href="http://github.com/okfn/dataexplorer">original Data Explorer</a>.
-    However, it has been rapidly rewritten from the ground up using Backbone.</p>
+    However, it has been rewritten from the ground up using Backbone.</p>
 
   </div>
 </div>