diff --git a/rw-stream-sink/README.md b/rw-stream-sink/README.md
new file mode 100644
index 00000000..6d54ed54
--- /dev/null
+++ b/rw-stream-sink/README.md
@@ -0,0 +1,8 @@
+This crate provides the `RwStreamSink` type. It wraps around a `Stream + Sink` that produces
+and accepts byte arrays, and implements `AsyncRead` and `AsyncWrite`.
+
+Each call to `write()` will send one packet on the sink. Calls to `read()` will read from
+incoming packets.
+
+> **Note**: Although this crate is hosted in the libp2p repo, it is purely a utility crate and
+>           not at all specific to libp2p.
diff --git a/rw-stream-sink/src/lib.rs b/rw-stream-sink/src/lib.rs
index 29ca2060..b9de4e5f 100644
--- a/rw-stream-sink/src/lib.rs
+++ b/rw-stream-sink/src/lib.rs
@@ -18,8 +18,17 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 // DEALINGS IN THE SOFTWARE.
 
+// TODO: use this once stable ; for now we just copy-paste the content of the README.md
+//#![doc(include = "../README.md")]
+
 //! This crate provides the `RwStreamSink` type. It wraps around a `Stream + Sink` that produces
-//! byte arrays, and implements `AsyncRead` and `AsyncWrite`.
+//! and accepts byte arrays, and implements `AsyncRead` and `AsyncWrite`.
+//!
+//! Each call to `write()` will send one packet on the sink. Calls to `read()` will read from
+//! incoming packets.
+//!
+//! > **Note**: Although this crate is hosted in the libp2p repo, it is purely a utility crate and
+//! >           not at all specific to libp2p.
 
 extern crate bytes;
 extern crate futures;