remove remaining TODOs and fill in lots more info

README.rst

@@ -1,16 +1,18 @@
 About
 =====
 
-Matrix is an ambitious new ecosystem for open federated Instant Messaging and VoIP[1].
+Matrix is an ambitious new ecosystem for open federated Instant Messaging and
+VoIP[1].
 
-Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard, providing:
+Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
+providing:
 
     - Creating and managing fully distributed chat rooms with no
       single points of control or failure
-    - Eventually-consistent cryptographically secure synchronisation of room 
+    - Eventually-consistent cryptographically secure[2] synchronisation of room 
 	  state across a global open network of federated servers and services
     - Sending and receiving extensible messages in a room with (optional)
-      end-to-end encryption[2]
+      end-to-end encryption[3]
     - Inviting, joining, leaving, kicking, banning room members
     - Managing user accounts (registration, login, logout)
     - Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
@@ -18,11 +20,11 @@ Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
     - Placing 1:1 VoIP and Video calls (in development)
 
 These APIs are intended to be implemented on a wide range of servers, services
-and clients which then form the Matrix ecosystem, and allow developers to build
+and clients, letting developers build messaging and VoIP functionality on top of
-messaging and VoIP functionality on top of the open Matrix community rather than
+the entirely open Matrix ecosystem rather than using closed or proprietary
-using closed or proprietary solutions.  The hope is for Matrix to act as the
+solutions. The hope is for Matrix to act as the building blocks for a new
-building blocks for a new generation of fully open and interoperable messaging
+generation of fully open and interoperable messaging and VoIP apps for the
-and VoIP apps for the internet.
+internet.
 
 Synapse is a reference "homeserver" implementation of Matrix from the core
 development team at matrix.org, written in Python/Twisted for clarity and
@@ -38,15 +40,55 @@ control and own your own communications and history or use one hosted by someone
 else (e.g. matrix.org) - there is no single point of control or mandatory
 service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.
 
-Synapse ships with two basic demo Matrix clients: webclient (a basic group chat web client demo implemented in AngularJS) and cmdclient (a basic Python commandline utility which lets you easily see what the JSON APIs are up to).
+Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
+web client demo implemented in AngularJS) and cmdclient (a basic Python
+commandline utility which lets you easily see what the JSON APIs are up to).
 
-We'd like to invite you to take a look at the Matrix spec, try to run a homeserver, and join the existing Matrix chatrooms already out there, experiment with the APIs and the demo clients, and let us know your thoughts at https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
+We'd like to invite you to take a look at the Matrix spec, try to run a
+homeserver, and join the existing Matrix chatrooms already out there, experiment
+with the APIs and the demo clients, and let us know your thoughts at
+https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
 
 Thanks for trying Matrix!
 
-[1] VoIP currently in development
+.. [1] VoIP currently in development
+.. [2] Cryptographic signing of messages isn't turned on yet
+.. [3] End-to-end encryption is currently in development
 
-[2] End-to-end encryption is currently in development
+Quick Start
+===========
+
+The basics you need to know about Matrix are:
+
+    - Chatrooms look like ``#matrix:matrix.org`` or ``#test:localhost:8080``
+    
+    - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
+      you will normally refer to yourself and others using a 3PID: email
+      address, phone number, etc rather than manipulating matrix user IDs)
+      
+    - To simply play with an **existing** homeserver (e.g. matrix.org), you can
+      just go straight to http://matrix.org/alpha, specify a homeserver 
+      (defaults to matrix.org) and sign up and use it. (Sign-up security is
+      currently work-in-progress)
+    
+    - To run your own **private** homeserver on localhost:8080, install synapse 
+      with ``python setup.py develop --user`` and then run one with
+      ``python synapse/app/homeserver.py``
+      
+    - To run your own webclient:
+      ``cd webclient; python -m SimpleHTTPServer`` and hit http://localhost:8000
+      in your web browser (a recent Chrome, Safari or Firefox for now,
+      please...)
+       
+    - For now, register some accounts like ``@testing:localhost:8080`` from 
+      different browsers, join a room like ``#test:localhost:8080`` and have a 
+      play.
+      
+    - To quickly run a **public** homeserver that can exchange messages with 
+      other homeservers and participate in the overall Matrix federation, open 
+      up port 8080 and run ``python synapse/app/homeserver.py --host 
+      machine.my.domain.name``.  Then come join ``#matrix:matrix.org`` and
+      say hi! :)
     
 
 Directory Structure
@@ -58,10 +100,10 @@ Directory Structure
     ├── cmdclient           Basic CLI python Matrix client
     ├── demo                Scripts for running standalone Matrix demos
     ├── docs                All doc, including the draft Matrix API spec
-    │   ├── client-server   The client-server Matrix API spec
+    │   ├── client-server       The client-server Matrix API spec
-    │   ├── model           Domain-specific elements of the Matrix API spec
+    │   ├── model               Domain-specific elements of the Matrix API spec
-    │   ├── server-server   The server-server model of the Matrix API spec
+    │   ├── server-server       The server-server model of the Matrix API spec
-    │   └── sphinx          The internal API doc of the Synapse homeserver
+    │   └── sphinx              The internal API doc of the Synapse homeserver
     ├── experiments         Early experiments of using Synapse's internal APIs
     ├── graph               Visualisation of Matrix's distributed message store 
     ├── synapse             The reference Matrix homeserver implementation
@@ -82,13 +124,12 @@ Directory Structure
     └── webclient           Basic AngularJS Matrix web client
 
 
-Installation
+Homeserver Installation
-============
+=======================
 
 First, the dependencies need to be installed.  Start by installing 
 'python2.7-dev' and the various tools of the compiler toolchain.
-
+N.B. synapse requires python 2.x where x >= 7
-N.B. that python 2.x where x >= 7 is required.
 
   Installing prerequisites on ubuntu::
 
@@ -103,6 +144,12 @@ to install by making setup.py do so, in --user mode::
 
     $ python setup.py develop --user
     
+You'll need a version of setuptools new enough to know about git, so you
+may need to also run:
+
+    $ sudo apt-get install python-pip
+    $ sudo pip install --upgrade setuptools
+
 This will run a process of downloading and installing into your
 user's .local/lib directory all of the required dependencies that are
 missing.
@@ -161,6 +208,14 @@ For the initial alpha release, the homeserver is not speaking TLS for
 either client-server or server-server traffic for ease of debugging. We have
 also not spent any time yet getting the homeserver to run behind loadbalancers.
 
+Running a Demo Federation of Homeservers
+----------------------------------------
+
+If you want to get up and running quickly with a trio of homeservers in a
+private federation (``localhost:8080``, ``localhost:8081`` and
+``localhost:8082``) which you can then point a demo webclient at, simply run::
+
+    $ demo/start.sh
 
 Running The Demo Web Client
 ===========================
@@ -200,19 +255,43 @@ synapse sandbox running on localhost)
 Logging In To An Existing Account
 ---------------------------------
 
-[[TODO(paul): It seems the current web client still requests an access_token -
+Just enter the ``@localpart:my.domain.here`` matrix user ID and password into the form and click the Login button.
-  I suspect this part will need updating before we can point people at how to
-  perform e.g. user+password or 3PID authenticated login]]
 
 
-Building Documentation
+Identity Servers
+================
+
+The job of authenticating 3PIDs and tracking which 3PIDs are associated with a
+given matrix user is very security-sensitive, as there is obvious risk of spam
+if it is too easy to sign up for Matrix accounts or harvest 3PID data. Meanwhile
+the job of publishing the end-to-end encryption public keys for Matrix users is
+also very security-sensitive for similar reasons.
+
+Therefore the role of managing trusted identity in the Matrix ecosystem is
+farmed out to a cluster of known trusted ecosystem partners, who run 'Matrix
+Identity Servers' such as ``sydent``, whose role is purely to authenticate and
+track 3PID logins and publish end-user public keys.
+
+It's currently early days for identity servers as Matrix is not yet using 3PIDs
+as the primary means of identity and E2E encryption is not complete. As such,
+we're not yet running an identity server in public.
+
+
+How does it all work?!
 ======================
 
-Before building documentation install spinx and sphinxcontrib-napoleon::
+For now, please go spelunking in the ``docs/`` directory to find out.
+
+
+Building Internal API Documentation
+===================================
+
+Before building internal API documentation install spinx and
+sphinxcontrib-napoleon::
 
     $ pip install sphinx
     $ pip install sphinxcontrib-napoleon
 
-Building documentation::
+Building internal API documentation::
 
     $ python setup.py build_sphinx