diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..23c5e6e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2018, dwyl
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
index bb4b2d4..552e888 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,86 @@
 # elm-criteria
 [![Build Status](https://travis-ci.org/dwyl/elm-criteria.svg?branch=master)](https://travis-ci.org/dwyl/elm-criteria)
+[![HitCount](http://hits.dwyl.io/dwyl/elm-criteria.svg)](http://hits.dwyl.io/dwyl/elm-criteria)
 
-A reusable dropdown/filters Elm package
+This Elm package lets you create a dropdown/filters UI:
 
+![filters](https://user-images.githubusercontent.com/6057298/49626564-5d62bb00-f9d2-11e8-8cc6-0238b85215f0.png)
+
+## Use elm-criteria
+
+- import `Criteria` and initialise the `Criteria.State` in your model
+
+```elm
+import Criteria
+
+type alias Model =
+    { criteria : Criteria.State }
+
+
+init : Model
+init =
+    { criteria = Criteria.init }
+```
+
+- Define the configuration that will be passed to the view
+
+```elm
+criteriaConfig : Criteria.Config Msg Filter
+criteriaConfig =
+    Criteria.config
+        { title = "My filters"
+        , toMsg = UpdateCriteria
+        , toId = getFilterId
+        , toString = getFilterName
+        , getSubFilters = getSubFilters
+        }
+```
+
+`title`: The text displayed in the open/close button
+`toMsg`: The message in your application responsible for updating the new `Criteria.State` in your `Model`
+`toId`: A function which create a unique `String` representing a filter
+`toString`: A function which create the text displayed for a filter
+`getSubFilters`: A function which returns the list of sub filters for a specific filter
+
+- Define the `Msg` which will update the state
+
+```elm
+type Msg = UpdateCriteria Criteria.State
+
+update : Msg -> Model -> Model
+update msg model =
+    case msg of
+        UpdateCriteria state ->
+            { model | criteria = state }
+```
+
+- Finally display the `Criteria.view` in your view
+
+```elm
+view : Model -> Html Msg
+view model =
+    div []
+        [
+          Criteria.view criteriaConfig model.criteria filters
+        ]
+```
 ## Examples
 
-[example](https://dwyl.github.io/elm-criteria/example.html)
+See a [live example](https://dwyl.github.io/elm-criteria/example.html) and its [code]()
+
+To run the exmple on your machine:
+- clone this repository `git clone git@github.com:dwyl/elm-criteria.git && cd elm-criteria`
+- move to the `examples` directory: `cd examples`
+- run `elm reactor`
+- visit `localhost:8000` and select the example Elm file you want to run
+
+## Tests
+
+To run the tests make sure to have installed the dependencies of the package with `elm install` then run `elm-test --verbose`:
+
+![tests](https://user-images.githubusercontent.com/6057298/49627193-70c35580-f9d5-11e8-95d3-8313258ad58c.png)
+
+## Releases
+| Version | Notes |
+| ------- | ----- |
+|  [**1.0.0**](https://github.com/dwyl/elm-criteria/releases/tag/1.0.0) | elm-criteria initial release