diff --git a/README.md b/README.md
index 6056a41..e8f709e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,38 @@
 # Shortener
 
-This is an small wrapper around the ethical shortener service https://is.gd. 
-
-Migrated from: http://static.smalltalkhub.com/Offray/Shortener/index.html
\ No newline at end of file
+This is an small wrapper around the [ethical shortener](https://is.gd/ethics.php) service <https://is.gd>.
+
+## Installation
+
+Run this two steps in a playground:
+
+```smalltalk
+"Start by loading the configuration of Shortener"
+  Gofer new
+    url: 'http://smalltalkhub.com/mc/Offray/Shortener/main';
+    package: 'ConfigurationOfShortener';
+  load.
+
+"After that load Shortener"
+ConfigurationOfShortener load.
+```
+
+## Usage
+
+* To shorten a link do:
+
+  `Shortener shorten: 'https://pharo.org'`, which produces something like: `'https://is.gd/cQWvtm'
+
+* To enlarge a link do:
+
+  `Shortener enlarge: 'https://is.gd/cQWvtm'`, which, conversely, produces `'https://pharo.org'
+
+* To shorten a link with an explicit alias do:
+
+  `Shortener shorten: 'https://pharo.org' as: 'pharo'`, which produces `'https://is.gd/pharo'`.
+
+  or will raise an error once a short url have been taken. 
+  For example, by running the previous example the alias 'pharo' has been taken for all future 
+  short urls and can not be used again (you will need to pick a new short url alias).
+
+Migrated from: <http://static.smalltalkhub.com/Offray/Shortener/index.html>
\ No newline at end of file