diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a6413e1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+ # freedesktop-icons
+
+ This crate provides a [freedesktop icon](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html#implementation_notes) lookup implementation.
+
+ It exposes a single `lookup` function to find icon based on their, `name`, `theme`, `size` and `scale`.
+
+ ## Example
+
+ **Simple lookup:**
+
+ The following snippet get an icon from the default 'hicolor' theme
+ with the default scale (`1`) and the default size (`24`).
+
+ ```rust
+ use freedesktop_icons::lookup;
+
+ let icon = lookup("firefox").find();
+```
+
+ **Complex lookup:**
+
+ If you have specific requirement for your lookup you can use the provided builder functions:
+
+ ```rust
+ use freedesktop_icons::lookup;
+
+ let icon = lookup("firefox")
+     .with_size(48)
+     .with_scale(2)
+     .with_theme("Arc")
+     .find();
+```
+ **Cache:**
+
+ If your application is going to repeat the same icon lookups multiple times
+ you can use the internal cache to improve performance.
+
+ ```rust
+ use freedesktop_icons::lookup;
+
+ let icon = lookup("firefox")
+     .with_size(48)
+     .with_scale(2)
+     .with_theme("Arc")
+     .with_cache()
+     .find();
+```
\ No newline at end of file
diff --git a/src/lib.rs b/src/lib.rs
index 68341b6..783424a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,8 +1,8 @@
-//! # freedesktop-incons
+//! # freedesktop-icons
 //!
 //! This crate provides a [freedesktop icon](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html#implementation_notes) lookup implementation.
 //!
-//! It exposes a single [`lookup`] function to find icon based on their, `name`, `theme`, `size` and `scale`.
+//! It exposes a single lookup function to find icon based on their, `name`, `theme`, `size` and `scale`.
 //!
 //! ## Example
 //!
@@ -36,7 +36,7 @@
 //!```
 //! **Cache:**
 //!
-//! If your application is going to repeat the same icon lookups multiple time
+//! If your application is going to repeat the same icon lookups multiple times
 //! you can use the internal cache to improve performance.
 //!
 //! ```rust
@@ -50,6 +50,7 @@
 //!     .with_cache()
 //!     .find();
 //! # }
+//! ```
 use crate::cache::{CacheEntry, CACHE};
 use crate::theme::{try_build_icon_path, THEMES};
 use std::path::PathBuf;