More readme cleanup

1 files changed, 95 insertions, 53 deletions

diff --git a/README.md b/README.md
index 718845ae..fd590aec 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 # Keystone: OpenStack Identity Service
-====================================
+======================================
 
 Keystone is a proposed independent authentication service for [OpenStack](http://www.openstack.org).
 
@@ -8,19 +8,14 @@ This initial proof of concept aims to address the current use cases in Swift and
 * REST-based, token auth for Swift
 * many-to-many relationship between identity and tenant for Nova.
 
-## DEVELOPER GUIDE/CONCEPTS:
-----------------------------
+# For Users
+===========
 
-The [dev guide](https://github.com/rackspace/keystone/raw/master/keystone/content/identitydevguide.pdf) is automatically
-generated from XML and other artifacts in the keystone/docs/src folder.
-
-To build the API dev guide, you need Maven. To build the docs, run the following from the
-keystone/docs folder:
-
-    $ mvn clean generate-sources
+## User Guide & Concepts
+------------------------
 
-The output will go into the keystone/docs/target folder (the source is in keystone/docs/src). Output
-generated is PDF and webhelp.
+The [`Developer Guide`](https://github.com/rackspace/keystone/raw/master/keystone/content/identitydevguide.pdf) 
+documents the APIs to call and how to use them.
 
 ### Core Concepts:
 <table>
@@ -28,7 +23,7 @@ generated is PDF and webhelp.
     <th>Concept</th><th align="left">Description</th>
   </tr>
   <tr>
-    <td>User</td><td>An identity stored in the Keystone identoty store used by a client to authenticate to Keystone.</td>
+    <td>User</td><td>An identity stored in the Keystone identity store used by a client to authenticate to Keystone.</td>
   </tr>
   <tr>
     <td>Tenant</td><td>A container which houses multiple resources. <br/>For example, a tenant might represent an 'account' or 'company' which contains an arbitrary number of compute resources. One or more users may be assiciated and have rights to a tenent.</td>
@@ -44,21 +39,41 @@ generated is PDF and webhelp.
   </tr>
 </table>
 
-## SERVICES:
-------------
+## Running Keystone
+-------------------
+
+#### Setup
+
+    $ sudo pip install -r tools/pip-requires
+    $ sudo python setup.py install
+
+#### Starting services
+Starting both Admin and Service API endpoints:
+
+    $ cd bin
+    $ ./keystone
+
+
+# For Keystone Contributors
+===========================
+
+## Components
+-------------
+
+#### Services
 
 * Keystone    - identity store and authentication service
 * Auth_Token  - WSGI middleware that can be used to handle token auth protocol (WSGI or remote proxy)
 * Echo        - A sample service that responds by returning call details
 
-Also included:
+#### Also included:
 
 * Keystone    - Service and Admin API are available separately. Admin API allows management of tenants, roles, and users as well.
 * Auth_Basic  - Stub for WSGI middleware that will be used to handle basic auth
 * Auth_OpenID - Stub for WSGI middleware that will be used to handle openid auth protocol (to be implemented)
 * RemoteAuth  - WSGI middleware that can be used in services (like Swift, Nova, and Glance) when Auth middleware is running remotely
 
-Built-In commands:
+#### Built-In commands:
 
 * bin/keystone  - Provides HTTP API for users and administrators
 * bin/keystone-admin - Provides HTTP API for administrators
@@ -67,8 +82,23 @@ Built-In commands:
 
 By default, configuration parameters are parsed from etc/keystone.conf.
 
-## RUNNING KEYSTONE:
---------------------
+## Dependencies
+---------------
+
+<pre>
+# Show Dependencies
+$ cat tools/pip-requires
+
+# Install Dependencies
+$ sudo pip install -r tools/pip-requires
+
+# Keystone uses the DTest test framework for testing. Install that separately using:
+$ sudo pip install DTest
+
+</pre>
+
+## Running Keystone
+-------------------
 
 Starting both Admin and Service API endpoints:
 
@@ -87,33 +117,20 @@ Starting the admin server only (exposes the Admin API):
 
 All above files take parameters from etc/keystone.conf file under the Keystone root folder by default
 
-## DEPENDENCIES:
-----------------
-
-<pre>
-# Show Dependencies
-$ cat tools/pip-requires
-
-# Install Dependencies
-$ sudo pip install -r tools/pip-requires
 
-# Keystone uses the DTest test framework for testing. Install that separately using:
-$ sudo pip install DTest
-
-</pre>
-
-###Running Tests:
+### Running Tests
 -----------------
 
+#### Test data
 A set of sample data can be added by running a shell script:
 
     $ ./bin/sampledata.sh
 
 The script calls keystone-manage to create the sample data.
 
-After starting keystone or running keystone-manage a keystone.db sqlite database should be created in the keystone folder.
-
+After starting keystone or running `keystone-manage` a keystone.db sqlite database should be created in the keystone folder.
 
+#### Demo
 To run client demo (with all auth middleware running locally on sample service):
 
     $ ./echo/bin/echod
@@ -121,6 +138,7 @@ To run client demo (with all auth middleware running locally on sample service):
 
 NOTE: NOT ALL TESTS CONVERTED TO NEW MODEL YET. MANY FAIL. THIS WILL BE ADDRESSED SOON.
 
+#### Unit Tests
 To run unit tests:
 
 * go to unit test/unit directory
@@ -139,23 +157,43 @@ For more on unit testing please refer
     $ python test_keystone.py --help
 
 
+#### API Validation
 To perform contract validation and load testing, use SoapUI (for now).
 
-
 Using SOAPUI:
 
-First, download [SOAPUI](http://sourceforge.net/projects/soapui/files/):
+1. First, download [SOAPUI](http://sourceforge.net/projects/soapui/files/):
 
-To Test Keystone Service:
+2. To Test Keystone Service:
 
 * File->Import Project
 * Select tests/IdentitySOAPUI.xml
 * Double click on "Keystone Tests" and press the green play (>) button
 
+
+## Editing and Compiling the Developer Guide
+--------------------------------------------
+
+Users of the Keystone API are often developers making ReSTfull calls to Keystone. The guide to provide them
+information is therefore called a `Developer Guide`. Developer in this case is not to be confused with developers
+working on the Keystone source code itself.
+
+The [dev guide](https://github.com/rackspace/keystone/raw/master/keystone/content/identitydevguide.pdf) is automatically
+generated from XML and other artifacts in the `keystone/docs/src` folder.
+
+To build the API `dev guide` from source, you need [Maven](http://maven.apache.org/). To build the docs,
+run the following from the `Keystone/docs` folder:
+
+    $ mvn clean generate-sources
+
+The output will go into the `keystone/docs/target` folder (the source is in `keystone/docs/src`). Output
+generated is PDF and webhelp.
+
+
 ## Additional Information:
 --------------------------
 
-Configuration:
+#### Configuration:
 Keystone gets its configuration from command-line parameters or a .conf file. The file can be provided explicitely
 on the command line otherwise the following logic applies (the conf file in use will be output to help
 in troubleshooting:
@@ -165,12 +203,13 @@ in troubleshooting:
     /etc/keystone.conf or /etc/keystone/keystone.conf have higher priority than <top_dir>/etc/keystone.conf.
 
 CURL commands:
-
+<pre>
    $ curl -d '{"passwordCredentials": {"username": "joeuser", "password": "secrete"}}' -H "Content-type: application/json" http://localhost:8081/v2.0/tokens
 
    $ curl -d '{"passwordCredentials": {"username": "joeuser", "password": "secrete", "tenant": "1234"}}' -H "Content-type: application/json" http://localhost:8081/v2.0/tokens
+</pre>
 
-Load Testing:
+#### Load Testing:
 
    $ # Create post data
 
@@ -181,8 +220,8 @@ Load Testing:
    $ ab -c 30 -n 1000 -T "application/json" -p post_data http://127.0.0.1:8081/v2.0/tokens
 
 
-## NOVA Integration:
---------------------
+## NOVA Integration
+-------------------
 
 Initial support for using keystone as nova's identity component has been started.
 
@@ -198,8 +237,8 @@ Initial support for using keystone as nova's identity component has been started
 
 Assuming you added the test data using bin/sampledata.sh, you can then use joeuser/secrete
 
-## I WANT OPENSTACK:
---------------------
+## I want OpenStack (all of it)
+-------------------------------
 
 To get an opinionated install of nova, keystone, dashboard and glance using openstack apis:
 
@@ -218,16 +257,19 @@ To get an opinionated install of nova, keystone, dashboard and glance using open
     ./nova.sh run
 
 
-## INTERESTING TECHNOLOGIES/STANDARDS/LINKS:
+## Relevant Technologies, Standards, and Links
 --------------------------------------------
-Protocols we could potentially integrate:
 
-WebID
+### Protocols
+We could potentially integrate with those:
+
+[WebID](http://www.w3.org/2005/Incubator/webid/spec/)
+
+    See also: http://www.w3.org/wiki/Foaf+ssl
 
-    http://www.w3.org/2005/Incubator/webid/spec/
-    http://www.w3.org/wiki/Foaf+ssl
+[OpenID](http://openid.net/) and/or [OpenIDConnect](http://openidconnect.com/)
 
-OpenID or OpenIDConnect
+[OAUTH2](http://oauth.net/2/)
 
-SAML
+[SAML] (http://saml.xml.org/)