Better README.md with SPORE project overview and links to examples.

1 files changed, 20 insertions, 5 deletions

diff --git a/README.md b/README.md
index a6d82ea..5567419 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,24 @@
 # SPORE - Specification to a POrtable Rest Environment
 
-## SPECIFICATIONS
+SPORE is a way to describe public services HTTP APIs such as [twitter] [1]
+or applications with an HTTP interface such as [Apache CouchDB] [2]
+using a simple language-agnostic JSON document that can be used by
+various language-specific implementations to dynamically or statically
+generate high level client objects.
 
- *  [API Description](http://github.com/spore/api-description)
- *  [Client Implementation](http://github.com/spore/)
+The goal of this git repository is to host:
 
-## DISCUSSIONS
+ * the specifications for the [SPORE description language] [3]
+ * the specifications for writing a [SPORE client implementation] [4]
 
- * [mailling list](http://groups.google.com/group/spore-rest)
+[1]: http://github.com/SPORE/api-description/blob/master/services/twitter.json
+[2]: http://github.com/SPORE/api-description/blob/master/apps/couchdb.json
+[3]: http://github.com/SPORE/specifications/blob/master/spore_description.pod
+[4]: http://github.com/SPORE/specifications/blob/master/spore_implementation.pod
+
+## APPLICATIONS AND SERVICES API DESCRIPTIONS
+
+ *  [API Descriptions](http://github.com/spore/api-description)
 
 ## IMPLEMENTATIONS
 
@@ -18,3 +29,7 @@
  * [Perl](http://github.com/franckcuny/net-http-spore)
  * [Python](http://github.com/elishowk/pyspore)
  * [Ruby](http://github.com/sukria/Ruby-Spore)
+
+## DISCUSSIONS
+
+ * [mailling list](http://groups.google.com/group/spore-rest)