feat(readme): add pull-streams documentation

README.md

@@ -10,15 +10,11 @@
 ![](https://raw.githubusercontent.com/libp2p/interface-connection/master/img/badge.png)
 ![](https://raw.githubusercontent.com/libp2p/interface-transport/master/img/badge.png)
 
-> Node.js implementation of the TCP module that libp2p uses, which implements
-> the [interface-connection](https://github.com/libp2p/interface-connection)
-> interface for dial/listen.
+> Node.js implementation of the TCP module that libp2p uses, which implements the [interface-connection](https://github.com/libp2p/interface-connection) interface for dial/listen.
 
 ## Description
 
-`libp2p-tcp` in Node.js is a very thin shim that adds support for dialing to a
-`multiaddr`. This small shim will enable libp2p to use other different
-transports.
+`libp2p-tcp` in Node.js is a very thin shim that adds support for dialing to a `multiaddr`. This small shim will enable libp2p to use other different transports.
 
 **Note:** This module uses [pull-streams](https://pull-stream.github.io) for all stream based interfaces.
 
@@ -71,6 +67,30 @@ hello
 > npm i libp2p-tcp
 ```
 
+## 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 istance of a Node.js Stream
+```
+
+To learn more about his utility, visit https://pull-stream.github.io/#pull-stream-to-stream
+
 ## API
 
 [![](https://raw.githubusercontent.com/diasdavid/interface-transport/master/img/badge.png)](https://github.com/diasdavid/interface-transport)