more documentation on use and setup

README.md

@@ -1,34 +1,20 @@
-# roe-base
+# River of Ebooks
 
-a [Sails v1](https://sailsjs.com) application
+## About
+The River of Ebooks serves as an easy-to-use ebook aggregator. Publishers can send metadata from new and updated ebooks through the River where it will be available for any downstream consumers to read, allowing for a more widely available ebook collection. This way, ebooks can be made available on all end user sites, instead of only the site they were published with.
 
+-----
 
 ### Links
-
-+ [Get started](https://sailsjs.com/get-started)
 + [Sails framework documentation](https://sailsjs.com/documentation)
-+ [Version notes / upgrading](https://sailsjs.com/documentation/upgrading)
-+ [Deployment tips](https://sailsjs.com/documentation/concepts/deployment)
-+ [Community support options](https://sailsjs.com/support)
-+ [Professional / enterprise options](https://sailsjs.com/enterprise)
-
 
 ### Version info
-
 This app was originally generated on Tue Oct 16 2018 01:21:31 GMT+0000 (UTC) using Sails v1.0.2.
-
 <!-- Internally, Sails used [`sails-generate@1.15.28`](https://github.com/balderdashy/sails-generate/tree/v1.15.28/lib/core-generators/new). -->
 
-
-
-<!--
-Note:  Generators are usually run using the globally-installed `sails` CLI (command-line interface).  This CLI version is _environment-specific_ rather than app-specific, thus over time, as a project's dependencies are upgraded or the project is worked on by different developers on different computers using different versions of Node.js, the Sails dependency in its package.json file may differ from the globally-installed Sails CLI release it was originally generated with.  (Be sure to always check out the relevant [upgrading guides](https://sailsjs.com/upgrading) before upgrading the version of Sails used by your app.  If you're stuck, [get help here](https://sailsjs.com/support).)
--->
-
-[![Build Status](https://travis-ci.org/miacona96/RoE-pipe.svg?branch=master)](https://travis-ci.org/miacona96/RoE-pipe)
-
-
 ### Setup
+a [Sails v1](https://sailsjs.com) application
+[![Build Status](https://travis-ci.org/miacona96/RoE-pipe.svg?branch=master)](https://travis-ci.org/miacona96/RoE-pipe)
 
 #### Standalone
 

docs/api.md

@@ -23,7 +23,7 @@ and body:
 
 Each tuple of `(title, author, version, isbn)` must be unique.
 
-The `opds` parameter is an opds2 file sent along with the post body.
+The `opds` parameter is an opds2 file containing an opds Publication sent along with the post body.
 
 The server will respond with either:
 

docs/integrations.md

@@ -0,0 +1,13 @@
+# River of Ebooks Integrations
+## Information on existing RoE integrations with other websites and services
+
+
+### readthedocs.org
+[view on github](https://github.com/ghowardsit/readthedocs.org)
+New ebooks published using ReadTheDocs will automatically be sent to the River of Ebooks.
+
+
+## Information on building your own integration
+
+To publish ebook metadata through the River of Ebooks, you will first need to register an account and then create a publisher.
+Verifying your ownership of the publisher's domain will increase the chance that your publisher is whitelisted. Once whitelisted, you will be able to use your publisher's appid (key) and secret to POST metadata through the River. You can view the [API documentation here](docs/api). Publishing books is easy - and once published, each new ebook will be available for downstream consumers to find.

docs/webhooks.md

@@ -1,4 +1,9 @@
 # River of Ebooks signed requests
+## Information on how to receive new publications from RoE
+
+To have RoE send your service any newly published or updated ebooks, you will first need to register an account and then create a Push URI. RoE will send a POST request containing the OPDS2 metadata from any published or updated book to each valid URL. The POST body structure can be viewed in the [API documentation](docs/api).
+
+
 ## Information on how to verify that requests are sent by RoE
 
 1. Grab your Signing Secret from the bottom of the 'My account' page. In this example, the Signing Secret is `919ac0b6c07b50`. Additionally, extract the raw request body from the request.