diff --git a/lib_eio/flow.mli b/lib_eio/flow.mli
index c94c0d12e..5576e2916 100644
--- a/lib_eio/flow.mli
+++ b/lib_eio/flow.mli
@@ -70,8 +70,13 @@ end
 val write : #sink -> Cstruct.t list -> unit
 (** [write dst bufs] writes all bytes from [bufs].
 
-    This is a low level API, consider using {!copy} if possible as it
-    may allow optimizations. *)
+    You should not perform multiple concurrent writes on the same flow
+    (the output may get interleaved).
+
+    This is a low level API. Consider using:
+
+    - {!Buf_write} to combine multiple small writes.
+    - {!copy} for bulk transfers, as it allows some extra optimizations. *)
 
 val copy : #source -> #sink -> unit
 (** [copy src dst] copies data from [src] to [dst] until end-of-file. *)
diff --git a/lib_main/eio_main.mli b/lib_main/eio_main.mli
index f69535ac1..df92b0efd 100644
--- a/lib_main/eio_main.mli
+++ b/lib_main/eio_main.mli
@@ -4,6 +4,7 @@ val run : (Eio_unix.Stdenv.base -> 'a) -> 'a
 (** [run fn] runs an event loop and then calls [fn env] within it.
 
     [env] provides access to the process's environment (file-system, network, etc).
+    [env] itself and the resources inside it can be shared safely between Eio domains.
 
     When [fn] ends, the event loop finishes.