diff --git a/README.md b/README.md
index 1d56f76..9ad28dc 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,14 @@
 [![](https://img.shields.io/badge/project-multiformats-blue.svg?style=flat-square)](http://github.com/multiformats/multiformats)
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
 
-> multiaddr implementation in go
+> [multiaddr](https://github.com/multiformats/multiaddr) implementation in go
 
-This is a [multiaddr](https://github.com/multiformats/multiaddr) implementation in Go.
+Multiaddr is a standard way to represent addresses that:
+- Support any standard network protocols.
+- Self-describe (include protocols).
+- Have a binary packed format.
+- Have a nice string representation.
+- Encapsulate well.
 
 ## Table of Contents
 
@@ -54,7 +59,7 @@ m2.Equal(m1)
 
 ```go
 // get the multiaddr protocol description objects
-addr.Protocols()
+ma.Protocols()
 // []Protocol{
 //   Protocol{ Code: 4, Name: 'ip4', Size: 32},
 //   Protocol{ Code: 17, Name: 'udp', Size: 16},