diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000..7ec0550
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,17 @@
+# partial-sort
+
+A rust implementation of [partial-sort algorithm](https://en.wikipedia.org/wiki/Partial_sorting)
+based on [mesuvash's gist](https://gist.github.com/mesuvash/4095565).
+
+### Example
+``` rust
+extern crate partial_sort;
+use partial_sort::partial_sort;
+
+let mut v = vec![5, 7, 4, 2, 8, 6, 1, 9, 0, 3];
+partial_sort(&mut v[..], 3);
+
+assert_eq!(v[0], 0);
+assert_eq!(v[1], 1);
+assert_eq!(v[2], 2);
+```
diff --git a/src/lib.rs b/src/lib.rs
index 65c861b..a4edb0d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -61,6 +61,8 @@ pub fn partial_sort_by<T, F: FnMut(&T, &T) -> Ordering>
 /// assert_eq!(v[1], 1);
 /// assert_eq!(v[2], 2);
 /// ```
+///
+/// The implementation is based on [this gist](https://gist.github.com/mesuvash/4095565).
 pub fn partial_sort<T: Ord>(slice: &mut [T], k: usize) {
     partial_sort_by(slice, k as isize, &mut |x, y| x.cmp(y));
 }