diff --git a/README.md b/README.md
index a3128d4..1a55f6f 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,12 @@ This library generates changelog for repositories using [gitmoji](https://gitmoj
 
 **Workflow:**
 1. Make changes and commit
+  ```
+  git commit . -m ":sparkles: my awesome feature"
+  ```
 2. Bump version in package.json
-3. `gitmoji-changelog`
-4. Commit package.json and changelog files
+3. Run `gitmoji-changelog`, the file `changelog.md` is created or updated with the summary of all changes in the release. See the example below.
+4. Commit `package.json` and `changelog` files
 5. Tag and push
 
 ### CLI
@@ -27,6 +30,37 @@ gitmoji-changelog
 
 **// TODO**
 
+## Setup
+
+Install the lib in your PATH : 
+
+```bash
+npm install -g gitmoji-changelog
+```
+
+## Mapping
+
+When a commit is done with a gitmoji, the following mapping is used to group them : 
+
+| Categorie | Gitmoji |
+|---|---|
+| Added | :sparkles: :tada: :white_check_mark: :bookmark: :construction_worker: :chart_with_upwards_trend: :heavy_plus_sign: :loud_sound: |
+| Changed | :art: :zap: :lipstick: :rotating_light: :arrow_down: :arrow_up: :pushpin: :recycle: :wrench: :rewind: :alien: :truck: :boom: :bento: :wheelchair: :speech_balloon: :card_file_box: :children_crossing: :building_construction: :iphone: |
+| Removed | :fire: :heavy_minus_sign: :mute: |
+| Fixed | :bug: :ambulance: :apple: :penguin: :checkered_flag: :robot: :green_apple: :green_heart: :pencil2: |
+| Security | :lock: |
+
+
+> See [mapping.js](packages/gitmoji-changelog-core/src/mapping.js) for more details
+
+
+## Example
+
+Here is an example of the produced `changelog.md` produced : 
+
+![Changelog example](doc/screenshot.png)
+
+
 ## Roadmap
 
 ### MVP
diff --git a/doc/screenshot.png b/doc/screenshot.png
new file mode 100644
index 0000000..1cfc4dc
Binary files /dev/null and b/doc/screenshot.png differ