diff --git a/README.md b/README.md
new file mode 100644
index 00000000..1315658a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,22 @@
+# servant-client
+
+[![Build Status](https://secure.travis-ci.org/haskell-servant/servant-client.svg)](http://travis-ci.org/haskell-servant/servant-client)
+
+![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
+
+This library lets you derive automatically Haskell functions that let you query each endpoint of a *servant* webservice.
+
+## Example
+
+``` haskell
+type MyApi = "books" :> Get [Book] -- GET /books
+        :<|> "books" :> ReqBody Book :> Post Book -- POST /books
+
+myApi :: Proxy MyApi
+myApi = Proxy
+
+getAllBooks :: BaseUrl -> EitherT String IO [Book]
+postNewBook :: Book -> BaseUrl -> EitherT String IO Book
+-- 'client' allows you to produce operations to query an API from a client.
+(getAllBooks :<|> postNewBook) = client myApi
+```
\ No newline at end of file
diff --git a/servant-client.cabal b/servant-client.cabal
index dc2289e4..fac8899a 100644
--- a/servant-client.cabal
+++ b/servant-client.cabal
@@ -1,7 +1,21 @@
 name:                servant-client
 version:             0.2
--- synopsis:
--- description:
+synopsis: automatical derivation of haskell functions that let you query servant webservices
+description:
+  This library lets you derive automatically Haskell functions that
+  let you query each endpoint of a <http://hackage.haskell.org/package/servant servant> webservice.
+  .
+  Example below.
+  .
+  > type MyApi = "books" :> Get [Book] -- GET /books
+  >         :<|> "books" :> ReqBody Book :> Post Book -- POST /books
+  >
+  > myApi :: Proxy MyApi
+  > myApi = Proxy
+  >
+  > getAllBooks :: BaseUrl -> EitherT String IO [Book]
+  > postNewBook :: Book -> BaseUrl -> EitherT String IO Book
+  > (getAllBooks :<|> postNewBook) = client myApi
 license:             BSD3
 license-file:        LICENSE
 author:              Alp Mestanogullari, Sönke Hahn, Julian K. Arni
@@ -11,6 +25,11 @@ category:            Web
 build-type:          Simple
 cabal-version:       >=1.10
 tested-with:         GHC >= 7.8
+homepage:            http://haskell-servant.github.io/
+Bug-reports:         http://github.com/haskell-servant/servant-client/issues
+source-repository head
+  type: git
+  location: http://github.com/haskell-servant/servant-client.git
 
 library
   exposed-modules:
@@ -34,7 +53,7 @@ library
     , transformers
   hs-source-dirs: src
   default-language: Haskell2010
-  ghc-options: -O0 -Wall
+  ghc-options: -Wall
 
 test-suite spec
   type: exitcode-stdio-1.0