diff --git a/README.md b/README.md
index 4901f8da..04891f83 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,42 @@ fn main() {
 }
 ```
 
+## Low-Friction Sockets with Built-In Timeouts
+
+```rust
+#![feature(async_await)]
+
+use std::time::Duration;
+
+use async_std::{
+    prelude::*,
+    task,
+    io,
+    net::TcpStream,
+};
+
+async fn get() -> io::Result<Vec<u8>> {
+    let mut stream = TcpStream::connect("example.com:80").await?;
+    stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?;
+
+    let mut buf = vec![];
+
+    io::timeout(Duration::from_secs(5), async {
+        stream.read_to_end(&mut buf).await?
+        Ok(buf)
+    })
+}
+
+fn main() {
+    task::block_on(async {
+        let raw_response = get().await.expect("request");
+        let response = String::from_utf8(raw_response)
+            .expect("utf8 conversion");
+        println!("received: {}", response);
+    });
+}
+```
+
 ## Take a look around
 
 Clone the repo:
diff --git a/src/lib.rs b/src/lib.rs
index 42216a29..e7f9ee90 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -22,6 +22,42 @@
 //!     })
 //! }
 //! ```
+//!
+//! Use sockets in a familiar way, with low-friction built-in timeouts:
+//!
+//! ```no_run
+//! #![feature(async_await)]
+//!
+//! use std::time::Duration;
+//! 
+//! use async_std::{
+//!     prelude::*,
+//!     task,
+//!     io,
+//!     net::TcpStream,
+//! };
+//!
+//! async fn get() -> io::Result<Vec<u8>> {
+//!     let mut stream = TcpStream::connect("example.com:80").await?;
+//!     stream.write_all(b"GET /index.html HTTP/1.0\r\n\r\n").await?;
+//! 
+//!     let mut buf = vec![];
+//! 
+//!     io::timeout(Duration::from_secs(5), async {
+//!         stream.read_to_end(&mut buf).await?
+//!         Ok(buf)
+//!     })
+//! }
+//!
+//! fn main() {
+//!     task::block_on(async {
+//!         let raw_response = get().await.expect("request");
+//!         let response = String::from_utf8(raw_response)
+//!             .expect("utf8 conversion");
+//!         println!("received: {}", response);
+//!     });
+//! }
+//! ```
 
 #![feature(async_await)]
 #![cfg_attr(feature = "docs", feature(doc_cfg))]