diff --git a/src/moonpool.mli b/src/moonpool.mli
index 66b3164a..6edeb1e7 100644
--- a/src/moonpool.mli
+++ b/src/moonpool.mli
@@ -1,7 +1,12 @@
 (** Moonpool
 
   A pool within a bigger pool (ie the ocean). Here, we're talking about
-  pools of [Thread.t] which live within a fixed pool of [Domain.t].
+  pools of [Thread.t] that are dispatched over several [Domain.t] to
+  enable parallelism.
+
+  We provide several implementations of pools
+  with distinct scheduling strategies, alongside some concurrency
+  primitives such as guarding locks ({!Lock.t}) and futures ({!Fut.t}).
 *)
 
 module Pool = Pool
diff --git a/src/runner.mli b/src/runner.mli
index cda20720..3ac2f724 100644
--- a/src/runner.mli
+++ b/src/runner.mli
@@ -1,17 +1,13 @@
-(** Abstract runner.
+(** Interface for runners.
 
-    This provides an abstraction for running tasks in the background.
+    This provides an abstraction for running tasks in the background,
+    which is implemented by various thread pools.
     @since 0.3
 *)
 
 type task = unit -> unit
 
-type t = private {
-  run_async: task -> unit;
-  shutdown: wait:bool -> unit -> unit;
-  size: unit -> int;
-  num_tasks: unit -> int;
-}
+type t
 (** A runner.
 
     If a runner is no longer needed, {!shutdown} can be used to signal all
@@ -50,8 +46,11 @@ val run_wait_block : t -> (unit -> 'a) -> 'a
     and returns its result. If [f()] raises an exception, then [run_wait_block pool f]
     will raise it as well.
 
-    {b NOTE} be careful with deadlocks (see notes in {!Fut.wait_block}). *)
+    {b NOTE} be careful with deadlocks (see notes in {!Fut.wait_block}
+      about the required discipline to avoid deadlocks). *)
 
+(** This module is specifically intended for users who implement their
+    own runners. Regular users of Moonpool should not need to look at it. *)
 module For_runner_implementors : sig
   val create :
     size:(unit -> int) ->