docs

3 files changed, 65 insertions, 7 deletions

diff --git a/docs/build/front.rst b/docs/build/front.rst
new file mode 100644
index 0000000..586349b
--- /dev/null
+++ b/docs/build/front.rst
@@ -0,0 +1,46 @@
+============
+Front Matter
+============
+
+Information about the Dogpile project.
+
+Project Homepage
+================
+
+Dogpile is hosted on `Bitbucket <http://bitbucket.org>`_ - the lead project page is at https://bitbucket.org/zzzeek/dogpile.  Source
+code is tracked here using `Mercurial <http://mercurial.selenic.com/>`_.
+
+Releases and project status are available on Pypi at http://pypi.python.org/pypi/dogpile.
+
+The most recent published version of this documentation should be at http://packages.python.org/dogpile/.
+
+Installation
+============
+
+Install released versions of Dogpile from the Python package index with `pip <http://pypi.python.org/pypi/pip>`_ or a similar tool::
+
+    pip install dogpile
+
+Installation via source distribution is via the ``setup.py`` script::
+
+    python setup.py install
+
+Community
+=========
+
+Dogpile is developed by `Mike Bayer <http://techspot.zzzeek.org>`_, and is 
+loosely associated with the `Pylons Project <http://www.pylonsproject.org/>`_.
+As Dogpile's usage increases, it is anticipated that the Pylons mailing list and IRC channel
+will become the primary channels for support.
+
+Bugs
+====
+Bugs and feature enhancements to Dogpile should be reported on the `Bitbucket
+issue tracker
+<https://bitbucket.org/zzzeek/dogpile/issues?status=new&status=open>`_.  If you're not sure 
+that a particular issue is specific to either dogpile.cache or Dogpile, posting to the `dogpile.cache issue tracker <https://bitbucket.org/zzzeek/dogpile.cache/issues?status=new&status=open>`_
+is likely the better place to post first, but it's not critical either way.
+
+* `dogpile.cache issue tracker <https://bitbucket.org/zzzeek/dogpile.cache/issues?status=new&status=open>`_ (post here if unsure)
+* `dogpile issue tracker <https://bitbucket.org/zzzeek/dogpile/issues?status=new&status=open>`_
+
diff --git a/docs/build/index.rst b/docs/build/index.rst
index d7ad387..721d7bf 100644
--- a/docs/build/index.rst
+++ b/docs/build/index.rst
@@ -14,6 +14,7 @@ which provides for a basic cache API and sample backends based on the dogpile co
 .. toctree::
    :maxdepth: 2
 
+   front
    usage
    api
 
diff --git a/docs/build/usage.rst b/docs/build/usage.rst
index b2a9427..c629ede 100644
--- a/docs/build/usage.rst
+++ b/docs/build/usage.rst
@@ -1,6 +1,6 @@
-====================
-Dogpile Usage Guide
-====================
+===========
+Usage Guide
+===========
 
 At its core, Dogpile provides a locking interface around a "value creation" function.
 
@@ -11,10 +11,21 @@ provide examples that use successively more and more of these features, as
 we approach how a fully featured caching system might be constructed around
 Dogpile.
 
-Note that when using the `dogpile.cache <http://bitbucket.org/zzzeek/dogpile.cache>`_
-package, the constructs here provide the internal implementation for that system,
-and users of that system don't need to access these APIs directly (though understanding
-the general patterns is a terrific idea in any case).
+Do I Need to Learn Dogpile's API Directly?
+==========================================
+
+It's anticipated that most users of Dogpile will be using it indirectly via the
+`dogpile.cache <http://bitbucket.org/zzzeek/dogpile.cache>`_ caching
+front-end.  If you fall into this category, then the short answer is no.
+
+Dogpile provides core internals to the 
+`dogpile.cache <http://bitbucket.org/zzzeek/dogpile.cache>`_
+package, which provides a simple-to-use caching API, rudimental
+backends for Memcached and others, and easy hooks to add new backends.  
+Users of dogpile.cache
+don't need to know or access Dogpile's APIs directly, though a rough understanding
+the general idea is always helpful.
+
 Using the core Dogpile APIs described here directly implies you're building your own 
 resource-usage system outside, or in addition to, the one 
 `dogpile.cache <http://bitbucket.org/zzzeek/dogpile.cache>`_ provides.