diff --git a/README.md b/README.md
index c06d55f..386d18f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,116 @@
 NelmioApiDocBundle
 ==================
 
+## Installation ##
 
+Register the namespace in `app/autoload.php`:
+
+    // app/autoload.php
+    $loader->registerNamespaces(array(
+        // ...
+        'Nelmio'          => __DIR__.'/../vendor/bundles',
+    ));
+
+Register the bundle in `app/AppKernel.php`:
+
+    // app/AppKernel.php
+    public function registerBundles()
+    {
+        return array(
+            // ...
+            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
+        );
+    }
+
+Import the routing definition in `routing.yml`:
+
+    # app/config/routing.yml
+    NelmioApiDocBundle:
+        resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
+        prefix:   /
+
+Enable the bundle's configuration in `app/config/config.yml`:
+
+    # app/config/config.yml
+    nelmio_api_doc: ~
+
+
+## Usage ##
+
+### ApiDoc() annotation ###
+
+The bundle provides an `ApiDoc()` annotation for your controllers:
+
+``` php
+<?php
+
+namespace Your\Namespace;
+
+class YourController extends Controller
+{
+    /**
+     * @ApiDoc(
+     *  resource="true",
+     *  description="This is a description of your API method",
+     *  filters={
+     *      {"name"="a-filter", "dataType"="integer"},
+     *      {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
+     *  }
+     * )
+     */
+    public function getAction()
+    {
+    }
+
+    /**
+     * @ApiDoc(
+     *  description="Create a new Object",
+     *  formType="Your\Namespace\Form\Type\YourType"
+     * )
+     */
+    public function postAction()
+    {
+    }
+}
+```
+
+The following parameters are recognized:
+
+* `resource`: whether the method describes a resource or not;
+
+* `description`: a description of the API method;
+
+* `filters`: an array of filters;
+
+* `formType`: the Form Type associated to the method, useful for POST|PUT methods.
+
+Each _filter_ has to define a `name` parameter, but other parameters are free.
+
+If you set a `formType`, then the bundle automatically extracts parameters based on the given type,
+and determines for each parameter its data type, and if it's required or not.
+
+
+### Documentation on-the-fly ###
+
+By adding `_doc=1` to an URL, you will get the corresponding documentation if available.
+
+
+### Web Interface ###
+
+You can browse the whole documentation at: `http://yourproject/api/doc`.
+
+![](https://github.com/nelmio/NelmioApiDocBundle/tree/master/Resources/doc/webview.png)
+
+
+### Command ###
+
+A command is provided in order to dump the documentation in `json`, `markdown, or `html`.
+
+    api:doc:dump [--format="..."]
+
+The `--format` option allows to choose the format (default is: `markdown`).
+
+
+## Credits ##
+
+The design is heavily inspired by the [swagger-ui](https://github.com/wordnik/swagger-ui) project.