diff --git a/README.md b/README.md
index 9939021..4b1eeb3 100644
--- a/README.md
+++ b/README.md
@@ -10,5 +10,52 @@
 
 ![](https://github.com/raw/libp2p/interface-connection/master/img/badge.png)
 ![](https://github.com/raw/libp2p/interface-transport/master/img/badge.png)
-
 > JavaScript implementation of the WebSockets module that libp2p uses and that implements the interface-transport interface
+
+## Description
+
+`libp2p-websockets` is the WebSockets implementation compatible with libp2p.
+
+**Note:** This module uses [pull-streams](https://pull-stream.github.io) for all stream based interfaces.
+
+## Example
+
+```
+TODO
+```
+
+## Installation
+
+### npm
+
+```sh
+> npm i libp2p-websockets
+```
+
+## This module uses `pull-streams`
+
+We expose a streaming interface based on `pull-streams`, rather then on the Node.js core streams implementation (aka Node.js streams). `pull-streams` offers us a better mechanism for error handling and flow control guarantees. If you would like to know more about what took us to make this migration, see the discussion at this [issue](https://github.com/ipfs/js-ipfs/issues/362).
+
+You can learn more about pull-streams at:
+
+- [The history of Node.js streams, nodebp April 2014](https://www.youtube.com/watch?v=g5ewQEuXjsQ)
+- [The history of streams, 2016](http://dominictarr.com/post/145135293917/history-of-streams)
+- [pull-streams, the simple streaming primitive](http://dominictarr.com/post/149248845122/pull-streams-pull-streams-are-a-very-simple)
+- [pull-streams documentation](https://pull-stream.github.io/)
+
+### Converting `pull-streams` to Node.js Streams
+
+If you are a Node.js streams user, you can convert a pull-stream to Node.js Stream using the module `pull-stream-to-stream`, giving you an instance of a Node.js stream that is linked to the pull-stream. Example:
+
+```
+const pullToStream = require('pull-stream-to-stream')
+
+const nodeStreamInstance = pullToStream(pullStreamInstance)
+// nodeStreamInstance is an instance of a Node.js Stream
+```
+
+To learn more about his utility, visit https://pull-stream.github.io/#pull-stream-to-stream
+
+## API
+
+[![](https://github.com/raw/diasdavid/interface-transport/master/img/badge.png)](https://github.com/diasdavid/interface-transport)
diff --git a/package.json b/package.json
index ecaf025..696d69c 100644
--- a/package.json
+++ b/package.json
@@ -44,7 +44,7 @@
     "aegir": "^6.0.1",
     "chai": "^3.5.0",
     "gulp": "^3.9.1",
-    "interface-transport": "^0.3.1",
+    "interface-transport": "^0.3.3",
     "multiaddr": "^2.0.2",
     "pre-commit": "^1.1.3",
     "pull-goodbye": "0.0.1",