diff --git a/README.md b/README.md
index a8913fb..63e2299 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-peer-id JavaScript implementation
-=================================
+# peer-id
[](http://ipn.io)
[](http://webchat.freenode.net/?channels=%23ipfs)
@@ -7,13 +6,38 @@ peer-id JavaScript implementation
[](https://david-dm.org/diasdavid/js-peer-id)
[](https://github.com/feross/standard)
-> IPFS Peer Id implementation in JavaScript
+
+> [IPFS](https://github.com/ipfs/ipfs) Peer ID implementation in JavaScript.
# Description
-An IPFS Peer Id is based on a sha256 hash of the peer public key, using [multihash](https://github.com/jbenet/multihash)
+Generate, import, and export PeerIDs, for use with [IPFS](https://github.com/ipfs/ipfs).
-The public key is a base64 encoded string of a protobuf containing an RSA DER buffer. This uses a node buffer to pass the base64 encoded public key protobuf to the multihash for ID generation.
+*A Peer ID is the SHA-256 [multihash](https://github.com/jbenet/multihash) of a
+public key.*
+
+*The public key is a base64 encoded string of a protobuf containing an RSA DER
+buffer. This uses a node buffer to pass the base64 encoded public key protobuf
+to the multihash for ID generation.*
+
+# Example
+
+```js
+var PeerId = require('peer-id')
+var bs58 = require('bs58')
+
+var id = PeerId.create({ bits: 32 })
+
+console.log('id ', id.toB58String())
+console.log('priv key ', bs58.encode(id.privKey))
+console.log('pub key ', bs58.encode(id.pubKey))
+```
+
+```
+id QmeeLFb92nkZJGj3gXLqXrEMzCMYs6uBgQLVNbrcXEvYXk
+priv key 6ibrcPAbevzvPpkq6EA6XmLyuhmUrJrEvUfgQDtEiSEPzGnGU8Ejwf6b11DVm6opnFGo
+pub key 2BeBZVKJ9RQs4i4LbGv4ReEeuBA5dck2Gje3wt67e44XuyyPq5jE
+```
# Installation
@@ -23,23 +47,29 @@ The public key is a base64 encoded string of a protobuf containing an RSA DER bu
> npm i peer-id
```
-## Use in Node.js
+# Setup
+
+## Node.js
```JavaScript
var PeerId = require('peer-id')
```
-## Use in a browser with browserify, webpack or any other bundler
+## Browser: Browserify or Webpack
-The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
+The code published to npm that gets loaded on require is in fact a ES5
+transpiled version with the right shims added. This means that you can require
+it and use with your favourite bundler without having to adjust asset management
+process.
```JavaScript
var PeerId = require('peer-id')
```
-## Use in a browser Using a script tag
+## Browser: `
@@ -47,52 +77,81 @@ Loading this module through a script tag will make the `PeerId` obj available in
```
-# Usage
+# API
-### Creating a new Id
-
-```
-const PeerId = require('ipfs-peer')
-
-// Create a new Id
-const id = PeerId.create()
-
-// Recreate an Id from Hex string
-const id = PeerId.createFromHexString(str)
-
-// Recreate an Id from a Buffer
-const id = PeerId.createFromBytes(buf)
-
-// Recreate an B58 String
-const id = PeerId.createFromB58String(str)
-
-// Recreate from a Public Key
-const id = PeerId.createFromPubKey(pubKey)
-
-// Recreate from a Private Key
-const id = PeerId.createFromPrivKey(privKey)
+```js
+const PeerId = require('peer-id')
```
-### Exporting an Id
+## Create
-```
-// Print friendly format
-id.toPrint() // returns an object with id, privKey and pubKey in hex format
+### PeerId.create()
-// Export to an hex string
-id.toHexString()
+Generates a new Peer ID, complete with public/private keypair. A Peer ID has the
+following properties:
-// Export to Buffer
-id.toBytes() (same as id.id)
+- `pubKey` - Buffer containing the public key bytes
+- `privKey` - Buffer containing the private key bytes
+- `id` - Buffer containing the multihash bytes
-// Export to a B58 string
-id.toB58String()
+## Import
+
+### PeerId.createFromHexString(str)
+
+Creates a Peer ID from hex string representing the key's multihash.
+
+### PeerId.createFromBytes(buf)
+
+Creates a Peer ID from a buffer representing the key's multihash.
+
+### PeerId.createFromB58String(str)
+Creates a Peer ID from a Base58 string representing the key's multihash.
+
+### PeerId.createFromPubKey(pubKey)
+
+Creates a Peer ID from a buffer containing a public key.
+
+### PeerId.createFromPrivKey(privKey)
+
+Creates a Peer ID from a buffer containing a private key.
+
+## Export
+
+### id.toPrint()
+
+Returns an object with the ID's properties in hex format:
+```js
+{
+ id: 'QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi',
+ privKey: '080012a609308204a20201000282010100a608889914da08959d3a3db0734cee812c96...',
+ pubKey: '080012a60230820122300d06092a864886f70d01010105000382010f003082010a0282010...'
+}
```
-### Id format
+### id.toHexString()
+Returns the Peer ID's `id` as a hex string.
+
+```js
+1220d6243998f2fc56343ad7ed0342ab7886a4eb18d736f1b67d44b37fcc81e0f39f```
+
+### id.toBytes()
+
+Returns the Peer ID's `id` as a buffer.
+
+
+```js
+
```
-id.pubKey // Buffer containing the Public Key
-id.privKey // Buffer containing the Private Key
-id.id // Buffer containing the multihash
+
+### id.toB58String()
+
+Returns the Peer ID's `id` as a base58 string.
+
+```js
+QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi
```
+
+# License
+
+MIT