diff --git a/README.md b/README.md
index 1d56f76..5c168a6 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,15 @@
 [![](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 +60,7 @@ m2.Equal(m1)
 
 ```go
 // get the multiaddr protocol description objects
-addr.Protocols()
+m1.Protocols()
 // []Protocol{
 //   Protocol{ Code: 4, Name: 'ip4', Size: 32},
 //   Protocol{ Code: 17, Name: 'udp', Size: 16},
diff --git a/doc.go b/doc.go
index b82f0e5..d8c37b2 100644
--- a/doc.go
+++ b/doc.go
@@ -3,7 +3,7 @@ Package multiaddr provides an implementation of the Multiaddr network
 address format. Multiaddr emphasizes explicitness, self-description, and
 portability. It allows applications to treat addresses as opaque tokens,
 and to avoid making assumptions about the address representation (e.g. length).
-Learn more at https://github.com/jbenet/multiaddr
+Learn more at https://github.com/multiformats/multiaddr
 
 Basic Use:
 
diff --git a/interface.go b/interface.go
index f8f2f6a..c68e4b4 100644
--- a/interface.go
+++ b/interface.go
@@ -3,7 +3,7 @@ package multiaddr
 /*
 Multiaddr is a cross-protocol, cross-platform format for representing
 internet addresses. It emphasizes explicitness and self-description.
-Learn more here: https://github.com/jbenet/multiaddr
+Learn more here: https://github.com/multiformats/multiaddr
 
 Multiaddrs have both a binary and string representation.