From 7b8dc91d241c92962267c70590a425b3dd94511d Mon Sep 17 00:00:00 2001
From: gered <gered@blarg.ca>
Date: Sat, 4 Jun 2016 16:26:14 -0400
Subject: [PATCH] beginning of documentation

---
 README.md                 | 44 ++++++++++++++++++++++++++++++++++-----
 views.reagent/project.clj |  2 +-
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index bce463f..724ae33 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,49 @@
 # views.reagent
 
-[Reagent][1] support for the [views][2] library, allowing Reagent components to
-reactively re-render based on server-side changes.
+[Reagent][1] plugin for the [views][2] library, providing real-time component updates to server-side changes to data.
 
 [1]: https://github.com/reagent-project/reagent
 [2]: https://github.com/gered/views
 
-### This library is still in the experimental stages! ###
+## Usage
+
+This library is made up of two core parts:
+
+* The actual library, views.reagent, providing core functionality.
+* A client/server communications plugin library which provides the glue code between whatever underlying client/server library you're using (e.g. [Sente][3] or [clj-browserchannel][4]) and views.reagent.
+
+[3]: https://github.com/ptaoussanis/sente
+[4]: https://github.com/gered/clj-browserchannel
+
+### Main Library Documentation
+
+[See here for full documentation.][5]
+
+[5]: https://github.com/gered/views.reagent/tree/master/views.reagent
+
+### Client/Server Plugin Documentation
+
+* **[views.reagent.sente][6]** provides fairly low-level integration with Sente.
+* **[views.reagent.browserchannel][7]** for using BrowserChannel for client/server communication.
+
+[6]: https://github.com/gered/views.reagent/tree/master/views.reagent.sente
+[7]: https://github.com/gered/views.reagent/tree/master/views.reagent.browserchannel
+
+
+### Notes
+
+views.reagent uses a separate plugin architecture for client/server communication mainly
+because I've observed that there are at times a variety of different ways in which people
+like to integrate client/server communications in their applications. I wanted to avoid
+(as much as possible) doing anything that would require any specific way of doing this
+kind of integration.
+
+As well, speaking for myself, I use my own custom helper library that wraps over Sente which
+I like but did not want to force anyone else to use.
+
+The client/server glue code provided by these libraries is incredibly light so if they
+do not meet your needs for whatever reason you should find it easy to create one yourself.
 
-I'm hoping to have a release with documentation and examples soon. For now, tread
-carefully when browsing through the code in this repository!
 
 ## License
 
diff --git a/views.reagent/project.clj b/views.reagent/project.clj
index c838fd5..fd9aeee 100644
--- a/views.reagent/project.clj
+++ b/views.reagent/project.clj
@@ -1,5 +1,5 @@
 (defproject gered/views.reagent "0.2.0-SNAPSHOT"
-  :description  "Reagent support for the views library, allowing Reagent components to reactively re-render based on server-side changes."
+  :description  "Reagent plugin for the views library, providing real-time component updates to server-side changes to data."
   :url          "https://github.com/gered/views.reagent"
   :license      {:name "MIT License"
                  :url  "http://opensource.org/licenses/MIT"}