diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d2b67e3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# simple-linguist
+
+File language detector and toolbox to ignore binary or vendored files. *simple-linguist*, is our port to _Go_ of the original [lignuist](https://github.com/github/linguist) _Ruby_ library, with fewer precision in arcane languages but with an improved *performance of 100x*.
+
+
+Installation
+------------
+
+The recommended way to install simple-linguist
+
+```
+go get github.com/src-d/simple-linguist
+```
+
+
+Examples
+--------
+
+```go
+lang, _ := GetLanguageByExtension("foo.go")
+fmt.Println(lang)
+// result: Go
+
+lang, _ = GetLanguageByContent("foo.m", "<matlab-code>")
+fmt.Println(lang)
+// result: Matlab
+
+lang, _ = GetLanguageByContent("bar.m", "<pbjective-c-code>")
+fmt.Println(lang)
+// result: Objective-C
+```
\ No newline at end of file