diff --git a/ChangeLog.md b/ChangeLog.md
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -1,3 +1,9 @@
+# Changelog for unliftio
+
+## 0.2.7.1
+
+* Minor doc improvements
+
 ## 0.2.7.0
 
 * Re-export `tryPutTMVar` from `UnliftIO.STM`
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -14,11 +14,13 @@
 the code here is lightly tested, the vast majority of it is simply apply
 `withUnliftIO` to existing functionality. Caveat emptor and all that.
 
+__NOTE__ The `UnliftIO.Exception` module in this library changes the semantics of asynchronous exceptions to be in the style of the `safe-exceptions` package, which is orthogonal to the "unlifting" concept. While this change is an improvment in most cases, it means that `UnliftIO.Exception` is not always a drop-in replacement for `Control.Exception` in advanced exception handling code. See [Async exception safety](#async-exception-safety) for details.
+
 ## Quickstart
 
 * Replace imports like `Control.Exception` with
   `UnliftIO.Exception`. Yay, your `catch` and `finally` are more
-  powerful and safer!
+  powerful and safer (see [Async exception safety](#async-exception-safety))!
 * Similar with `Control.Concurrent.Async` with `UnliftIO.Async`
 * Or go all in and import `UnliftIO`
 * Naming conflicts: let `unliftio` win
@@ -173,10 +175,10 @@
 timeout :: MonadUnliftIO m => Int -> m a -> m (Maybe a)
 timeout x y = do
   u <- askUnliftIO
-  System.Timeout.timeout x $ unliftIO u y
+  liftIO $ System.Timeout.timeout x $ unliftIO u y
 ```
 
-or more concisely using `withRunIO`:
+or more concisely using `withRunInIO`:
 
 ```haskell
 timeout :: MonadUnliftIO m => Int -> m a -> m (Maybe a)
@@ -185,7 +187,7 @@
 
 This is a common pattern: use `withRunInIO` to capture a run function,
 and then call the original function with the user-supplied arguments,
-applying `run` as necessary. `withRunIO` takes care of invoking
+applying `run` as necessary. `withRunInIO` takes care of invoking
 `unliftIO` for us.
 
 We can also use the run function with different types due to
@@ -357,7 +359,8 @@
 
 ## Async exception safety
 
-The `safe-exceptions` package builds on top of the `exceptions`
+The [`safe-exceptions`](https://hackage.haskell.org/package/safe-exceptions)
+package builds on top of the `exceptions`
 package and provides intelligent behavior for dealing with
 asynchronous exceptions, a common pitfall. This library provides a set
 of exception handling functions with the same async exception behavior
diff --git a/unliftio.cabal b/unliftio.cabal
--- a/unliftio.cabal
+++ b/unliftio.cabal
@@ -1,11 +1,13 @@
--- This file has been generated from package.yaml by hpack version 0.28.2.
+cabal-version: >= 1.10
+
+-- This file has been generated from package.yaml by hpack version 0.29.6.
 --
 -- see: https://github.com/sol/hpack
 --
--- hash: 70ba737e5c17d4578f0efa2cced9c38d03d68c4eb4988b294f73aedd28d74cc2
+-- hash: 80f98ec8618eddf5cd9e60732404c2af04ec9c97f9edefb9aa7b236b776e10ea
 
 name:           unliftio
-version:        0.2.7.0
+version:        0.2.7.1
 synopsis:       The MonadUnliftIO typeclass for unlifting monads to IO (batteries included)
 description:    Please see the documentation and README at <https://www.stackage.org/package/unliftio>
 category:       Control
@@ -16,7 +18,6 @@
 license:        MIT
 license-file:   LICENSE
 build-type:     Simple
-cabal-version:  >= 1.10
 extra-source-files:
     ChangeLog.md
     README.md