reword and clean documentation

docs/docs/configuration/client.rst

@@ -69,6 +69,8 @@ and not a multiple of 2, the color distribution is not even.
 data-isso-id
 ------------
 
+Broken – do not use. https://github.com/posativ/isso/issues/27
+
 Set a custom thread id, defaults to current URI. If you a comment counter, add
 this attribute to the link tag, too.
 

docs/docs/configuration/isso.conf

@@ -1 +0,0 @@
-../../../share/isso.conf

docs/docs/configuration/server.rst

@@ -3,8 +3,8 @@ Server Configuration
 
 The Isso configuration file is an `INI-style`__ textfile. It reads integers,
 booleans, strings and lists. Here's the default isso configuration:
-:download:`isso.conf <isso.conf>`. A basic configuration from
+`isso.conf <https://github.com/posativ/isso/blob/master/share/isso.conf>`. A
-scratch looks like this:
+basic configuration from scratch looks like this:
 
 .. code-block:: ini
 

docs/docs/index.rst

@@ -1,9 +1,9 @@
 Overview
 ========
 
-Welcome to the Isso's documentation. This documentation will help you get
+Welcome to Isso's documentation. This documentation will help you get started
-started fast. If you get any problems when using Isso, you can find the answer
+fast. If you get any problems when using Isso, you can find the answer in
-in troubleshooting or you can ask me on IRC or GitHub.
+troubleshooting guide or you can ask me on IRC or GitHub.
 
 Documentation overview:
 
@@ -19,7 +19,7 @@ What's Isso?
 
 Isso is a lightweight commenting server similar to Disqus. It allows anonymous
 comments, maintains identity and is simple to administrate. It uses JavaScript
-and cross-origin ressource sharing for easy integration into static websites.
+and cross-origin ressource sharing for easy integration into (static) websites.
 
 No, I meant "Isso"
 ------------------

docs/docs/install.rst

@@ -20,8 +20,8 @@ libraries, but most likely not all required by Isso (or in an up-to-date
 version – looking at you, Debian!).
 
 That's why most Python developers use the `Python Package Index`_ to get their
-packages. But the most important rule: never install *anything* from PyPi as
+dependencies. But the most important rule: never install *anything* from PyPi
-root. Not because of malicious software, but because you *will* break your
+as root. Not because of malicious software, but because you *will* break your
 system.
 ``easy_install`` is one tool to mess up your system. Another package manager is
 ``pip``. If you ever searched for an issue with Python/pip and Stackoverflow is
@@ -56,10 +56,9 @@ folder. Inside this virtual environment, you may also execute the example
 commands from above to upgrade your Python Package Manager (although it barely
 makes sense), it is completely independent from your global system.
 
-With a virtualenv ready, you may now continue to :ref:`install-from-pypi`!
+With a virtualenv active, you may now continue to :ref:`install-from-pypi`!
-Note, that if you are using a slightly more advanced shared-hoster or virtual
+Of course you may not need a virtualenv when you are running dedicated virtual
-machines, you may not need virtual environments.
+machines or a shared host (e.g. Uberspace.de).
-
 
 .. _Python Package Index: https://pypi.python.org/pypi
 .. _Why you should not use Python's easy_install carelessly on Debian:
@@ -72,7 +71,7 @@ Install from PyPi
 
 Requirements:
 
--  Python 2.6, 2.7 or 3.3 (+ devel headers)
+-  Python 2.6, 2.7 or 3.3+ (+ devel headers)
 -  SQLite 3.3.8 or later
 -  a working C compiler
 
@@ -88,15 +87,14 @@ Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:
 
     ~> easy_install isso  # cross your fingers
 
-If you are using a virtualenv, you don't need to activate the environment
+For easier execution, you can symlink the executable to a location in your
-every time you want to start Isso. You can symlink the executable to a location
+PATH:
-in your PATH:
 
 .. code-block:: sh
 
     ~> ln -s /path/to/isso-venv/bin/isso /usr/local/bin/isso
 
-To upgrade Isso, activate your virtual environment once again, and run
+To upgrade Isso, activate your virtual environment again, and run
 
 .. code-block:: sh
 
@@ -125,11 +123,12 @@ Install from Source
 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:
 
-- Python 2.6, 2.7 or 3.3 (+ devel headers)
+- Python 2.6, 2.7 or 3.3+ (+ devel headers)
+- Virtualenv
 - SQLite 3.3.8 or later
 - a working C compiler
 - Ruby 1.8 or higher
-- SASS 3.0 or higher
+- a `SCSS <http://sass-lang.com/>`_ compiler
 - Node.js, `NPM <https://npmjs.org/>`__ and `Bower <http://bower.io/>`__
 
 Get a fresh copy of Isso:
@@ -143,7 +142,6 @@ To create a virtual environment (recommended), run:
 
 .. code-block:: sh
 
-    ~> pip install virtualenv
     ~> virtualenv .
     ~> source ./bin/activate
 
@@ -166,14 +164,14 @@ Install JavaScript modules:
 
     ~> make init
 
-Integration without previous optimzation:
+Integration without previous optimization:
 
 .. code-block:: html
 
     <script src="/js/config.js"></script>
     <script data-main="/js/embed" src="/js/components/requirejs/require.js"></script>
 
-Optimization
+Optimization:
 
 .. code-block:: sh
 

docs/docs/quickstart.rst

@@ -2,7 +2,7 @@ Quickstart
 ==========
 
 Assuming you have successfully :doc:`installed <install>` Isso, here's
-a quickstart quide that covers common setups. Sections covered:
+a quickstart quide that covers the most common setup. Sections covered:
 
 .. contents::
     :local:
@@ -12,15 +12,14 @@ a quickstart quide that covers common setups. Sections covered:
 Configuration
 -------------
 
-You must provide a custom configuration. Most default parameters are useful for
+You must provide a custom configuration to set `dbpath` (your database
-development, not persistence. The two most important options are `dbpath` to
+location) and `host` (a list of websites for CORS_). All other options have
-set the location of your database and your website's name `host` where you want
+sane defaults.
-to comment on:
 
 .. code-block:: ini
 
     [general]
-    ; database location, check permissions, created if not exists
+    ; database location, check permissions, automatically created if not exists
     dbpath = /var/lib/isso/comments.db
     ; your website or blog (not the location of Isso!)
     host = http://example.tld/
@@ -36,9 +35,9 @@ Note, that multiple, *different* websites are **not** supported in a single
 configuration. To serve comments for diffent websites, refer to
 :ref:`Multiple Sites <configure-multiple-sites>`.
 
-You moderate Isso through signed URLs sent by email or logged. By default,
+The moderation is done with signed URLs sent by email or logged to stdout.
-comments are accepted and immediately shown to other users. To enable
+By default, comments are accepted and immediately shown to other users. To
-moderation queue, add:
+enable moderation queue, add:
 
 .. code-block:: ini
 
@@ -56,8 +55,8 @@ URLs for activation and deletion:
     [smtp]
     ; SMTP settings
 
-For more details, see :doc:`server <configuration/server>` and
+For more options, see :doc:`server <configuration/server>` and :doc:`client
-:doc:`client <configuration/client>` configuration.
+<configuration/client>` configuration.
 
 Migration
 ---------
@@ -67,13 +66,17 @@ your website, click on *Discussions* and select the *Export* tab. You'll
 receive an email with your comments. Unfortunately, Disqus does not export
 up- and downvotes.
 
-To import existing comments, run Isso with your new configuration file:
+To import existing comments, run Isso with your configuration file:
 
 .. code-block:: sh
 
     ~> isso -c /path/to/isso.cfg import user-2013-09-02T11_39_22.971478-all.xml
     [100%]  53 threads, 192 comments
 
+Migration from WordPress_ is not possible, yet (WordPress does not export
+comments). As a workaround, install the Disqus plugin, export to Disqus and
+then migrate to Isso.
+
 .. _Disqus: <https://disqus.com/>
 
 

docs/docs/usage.rst

@@ -1,2 +0,0 @@
-Usage
-=====

docs/index.html

@@ -15,9 +15,9 @@
     <ul>
         <li>
             <p><strong>Create, Edit and Remove Comments</strong></p>
-            <p>Commenters can edit or delete their own comments (within
+            <p>Users can edit or delete own comments (within 15 minutes by
-               15 minutes by default).</p>
+               default).</p>
-            <p>Comments in moderation queue are not publicly visible until
+            <p>Comments in moderation queue are not publicly visible before
                activation.</p>
         </li>
         <li>
@@ -30,7 +30,7 @@
         </li>
         <li>
             <p><strong>client-side JavaScript</strong></p>
-            <p>Embed a single JS file, 52kb (16kb gzipped) and you are
+            <p>Embed a single JS file, 51kb (16.5kb gzipped) and you are
                done.</p>
             <p>Supports Firefox, Safari, Chrome and IE10.</p>
         </li>