diff --git a/CHANGELOG.md b/CHANGELOG.md
index b45041c..c98e4a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,14 @@
 # Unreleased
 
-- Rename `StableHasherResult` to `FromStableHash` (#8)
-- Use new-type for returned-hash of `SipHasher128`(`Hash`) (#8)
-- Introduce multi hasher support (#8)
-- `StableHasher::finish` now returns a small hash instead of being fatal (#6)
-- Remove `StableHasher::finalize` (#4)
+# 0.1.0
+
+- Rename `StableHasherResult` to `FromStableHash` [#8][pr8]
+- Use new-type for returned-hash of `SipHasher128`(`Hash`) [#8][pr8]
+- Introduce multi hasher support [#8][pr8]
+- `StableHasher::finish` now returns a small hash instead of being fatal [#6][pr6]
+- Remove `StableHasher::finalize` [#4][pr4]
 - Import stable hasher implementation from rustc ([db8aca48129](/~https://github.com/rust-lang/rust/blob/db8aca48129d86b2623e3ac8cbcf2902d4d313ad/compiler/rustc_data_structures/src/))
+
+[pr8]: /~https://github.com/rust-lang/rustc-stable-hash/pull/8
+[pr6]: /~https://github.com/rust-lang/rustc-stable-hash/pull/6
+[pr4]: /~https://github.com/rust-lang/rustc-stable-hash/pull/4
diff --git a/README.md b/README.md
index 9ea3063..548ff21 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,32 @@
 # rustc-stable-hash
-A stable hashing algorithm used by rustc: cross-platform, deterministic, not secure
+
+[![crates.io](https://img.shields.io/crates/v/rustc-stable-hash.svg)](https://crates.io/crates/rustc-stable-hash)
+[![Documentation](https://docs.rs/rustc-stable-hash/badge.svg)](https://docs.rs/rustc-stable-hash)
+
+A stable hashing algorithm used by `rustc`: cross-platform, deterministic, not secure.
+
+This crate provides facilities with the `StableHasher` structure to create stable hashers over *unstable* hashers by abstracting over them the handling of endian-ness and the target `usize`/`isize` bit size difference.
+
+Currently, this crate provides it's own implementation of 128-bit `SipHasher`: `SipHasher128`; with `StableSipHasher128` for the stable variant. 
+
+## Usage
+
+```rust
+use rustc_stable_hash::hashers::{StableSipHasher128, SipHasher128Hash};
+use rustc_stable_hash::FromStableHash;
+use std::hash::Hasher;
+
+struct Hash128([u64; 2]);
+impl FromStableHash for Hash128 {
+    type Hash = SipHasher128Hash;
+
+    fn from(SipHasher128Hash(hash): SipHasher128Hash) -> Hash128 {
+        Hash128(hash)
+    }
+}
+
+let mut hasher = StableSipHasher128::new();
+hasher.write_usize(0xFA);
+
+let hash: Hash128 = hasher.finish();
+```