update README and add CONTRIBUTING page

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+Contributing
+============
+
+I appreciate any help and love pull requests. Here are some things
+you need to respect:
+
+* no hard-wired external services
+* no support for ancient browsers (e.g. IE6-9)
+
+Reporting Issues
+----------------
+
+### Disqus import fails
+
+If `isso import /path/to/disqus.xml` fails, please do *NOT* attach the raw
+dump file to GH:Issues. Please anonymize all IP addresses inside the `<ipAddress>`
+tag first, as second step, replace all email addresses with a generic one (
+email tag).
+
+### embed.min.js-related issues
+
+In case of a JavaScript traceback, please setup Isso in development mode
+described below. Otherwise it is very hard to "guess" the reason.
+
+### isso-related issues
+
+Copy and paste traceback into a ticket and provide some details of your usage.
+
+
+Development
+-----------
+
+If you want to hack on Isso or track down issues, there's an alternate
+way to set up Isso. It requires a lot more dependencies and effort.
+
+Requirements:
+
+- Python 2.6, 2.7 or 3.3
+- Ruby 1.8 or higher
+- Node.js, [NPM](https://npmjs.org/) and [Bower](http://bower.io/)
+
+On Debian/Ubuntu install the following packages
+
+    ~> sudo aptitude install python-setuptools python-dev npm ruby
+    ~> ln -s /usr/bin/nodejs /usr/bin/node
+
+Get the repository:
+
+    ~> git clone https://github.com/posativ/isso.git
+    ~> cd isso/
+
+Install `virtualenv` and create a new environment for Isso (recommended):
+
+    ~> pip install virtualenv
+    ~> virtualenv .
+    ~> source ./bin/activate
+
+Install Isso dependencies:
+
+    ~> python setup.py develop
+    ~> isso run
+
+Compile SCSS to CSS:
+
+    ~> gem install sass
+    ~> scss --watch isso/css/isso.scss
+
+Install JS components:
+
+    ~> cd isso/js
+    ~> bower install almond q requirejs requirejs-domready requirejs-text
+
+
+Integration
+-----------
+
+```html
+<link rel="stylesheet" href="/isso/static/isso.css" />
+<script src="/isso/js/config.js"></script>
+<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
+```
+
+
+Optimization
+------------
+
+    ~> npm install -g requirejs uglifyjs
+    ~> cd isso/js
+    ~> r.js -o build.embed.js
+    ~> r.js -o build.count.js

README.md

@@ -4,7 +4,7 @@ Isso – Ich schrei sonst
 You love static blog generators (especially [Acrylamid][1] *cough*) and the
 only option to interact with the community is [Disqus][2]. There's nothing
 wrong with it, but if you care about the privacy of your audience you are
-better off with a comment system that is under your control. This is, were
+better off with a comment system that is under your control. This is, where
 Isso comes into play.
 
 [1]: https://github.com/posativ/acrylamid
@@ -38,41 +38,15 @@ Roadmap
 Installation
 ------------
 
-Requirements:
+Note, there is currently no PyPi release, but I'll upload a snapshot
+infrequently. Nevertheless, here are the requirements:
 
-- Python 2.6 or 2.7
+- Python 2.6, 2.7 or 3.3
-- [NPM](https://npmjs.org/) and [Bower](http://bower.io/)
+- easy_install or pip
 
-On Debian/Ubuntu install the following packages
+Install Isso (and its dependencies) with:
 
-    ~> sudo aptitude install python-setuptools python-dev npm 
+    ~> pip install http://posativ.org/~tmp/isso-latest.tar.gz
-    ~> ln -s /usr/bin/nodejs /usr/bin/node 
-
-For now (as long as there is no stable version), you need to manually
-build everything:
-
-    ~> git clone https://github.com/posativ/isso.git
-    ~> cd isso/
-    ~> python setup.py develop
-
-To fetch the requires JS components, run:
-
-    ~> cd isso/js/
-    ~> bower install almond q requirejs requirejs-domready requirejs-text
-
-You can now either use the JS client as-is (using [require.js][r.js], see
-below) or compile all JS into a single file:
-
-    ~> cd isso/js
-    ~> npm install -g requirejs uglifyjs
-    ~> r.js -o build.embed.js
-    ~> r.js -o build.count.js
-
-At last, you need to build the CSS:
-
-    ~> cd ../css
-    ~> gem install sass
-    ~> scss isso.scss > isso.css
 
 Before you start, you may want to import comments from
 [Disqus.com](https://disqus.com/):
@@ -94,7 +68,7 @@ setup has its own benefits.
 
 ### Isso on a Sub URI
 
-Let's assume you want Isso on `/isso`, use the following nginx snippet
+Let's assume you want Isso on `/isso`, use the following nginx snippet:
 
 ```nginx
 server {
@@ -111,24 +85,42 @@ server {
 }
 ```
 
-The Isso API endpoint is now `example.tld/isso`, check by `curl`ing the client
+```html
-JS located at `http://example.tld/isso/js/embed.js`.
+<link rel="stylesheet" href="http://example.tld/isso/css/isso.css" />
+<script src="http://example.tld/isso/js/embed.min.js"></script>
+```
 
 ### Isso on a Dedicated Domain
 
-...
+Now, assuming you have your isso instance running on a different URL, such as
+`http://example.tld:8080`, but your blog runs on `http://example.tld`:
+
+    ~> cat example.cfg
+    [general]
+    host = http://example.tld/
+    ~> isso -c example.cfg run
+     * connecting to SMTP server [failed]
+     * connecting to HTTP server [ok]
+     * Running on http://localhost:8080/
+
+Make sure, Isso can connect to server that hosts your blog, otherwise you are
+not able to post comments.
+
+Integrate Isso with:
+
+```html
+<link rel="stylesheet" href="http://example.tld:8080/css/isso.css" />
+<script src="http://example.tld:8080/js/embed.min.js"></script>
+```
+
+Also, put the plain isso server behind a real web server or [use uWSGI][3].
+
+[3]: https://github.com/posativ/isso/blob/master/docs/CONTRIBUTING.md
 
 
 Website Integration
 -------------------
 
-Add the following two lines into your HTML header:
-
-```html
-<link rel="stylesheet" href="http://example.tld/isso/static/isso.css" />
-<script src="http://example.tld/isso/js/embed.min.js"></script>
-```
-
 To enable comments, add a `<div id="isso-thread"></div>` below your post and
 let the magic happen :-)
 
@@ -139,23 +131,14 @@ updated with the current comment count.
 This functionality is already included when you embed `embed.min.js`, do
 *not* mix `embed.min.js` and `count.min.js` in a single document.
 
-### Embed with require.js
-
-This section is primarily for developers: The client-side JS is modularized
-and uses an AMD loader for execution. You can easily hack on the JS files,
-when using [require.js][r.js]:
-
-```html
-<link rel="stylesheet" href="/isso/static/isso.css" />
-<script src="/isso/js/config.js"></script>
-<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
-```
 
 
-API
+Other Documents
----
+---------------
 
-See [docs/API.md](https://github.com/posativ/isso/blob/master/docs/API.md).
+- [Configuration](https://github.com/posativ/isso/raw/master/docs/CONFIGURATION.md)
+- [API overview](https://github.com/posativ/isso/raw/master/docs/API.md)
+- [uWSGI usage](https://github.com/posativ/isso/blob/master/docs/uWSGI.md)
 
 
 Alternatives
@@ -165,6 +148,3 @@ Alternatives
 - [Juvia](https://github.com/phusion/juvia) – Ruby on Rails
 - [Tildehash.com](http://www.tildehash.com/?article=why-im-reinventing-disqus) – PHP
 - [SO: Unobtrusive, self-hosted comments](http://stackoverflow.com/q/2053217)
-
-
-[r.js]: http://require.js/