diff --git a/lib_eio/file.mli b/lib_eio/file.mli
index 01bce61ae..c15c00e88 100644
--- a/lib_eio/file.mli
+++ b/lib_eio/file.mli
@@ -1,3 +1,8 @@
+(** Files implement the {!Flow} APIs, which can be used for reading and writing data.
+    This module provides additonal file-specific operations, such as seeking within a file.
+
+    To get an open file, use the functions in the {!Path} module. *)
+
 open Std
 
 (** {2 Types} *)
diff --git a/lib_eio/fs.ml b/lib_eio/fs.ml
index ec0bbea54..ad4a14834 100644
--- a/lib_eio/fs.ml
+++ b/lib_eio/fs.ml
@@ -1,7 +1,10 @@
-(** Defines types used by file-systems. *)
+(** Note: file-system operations, such as opening or deleting files,
+    can be found in the {!Path} module. *)
 
 open Std
 
+(** {2 Types} *)
+
 type path = string
 
 type error =
@@ -44,6 +47,8 @@ type dir_ty = [`Dir]
 type 'a dir = ([> dir_ty] as 'a) r
 (** Note: use the functions in {!Path} to access directories. *)
 
+(** {2 Provider Interface} *)
+
 module Pi = struct
   module type DIR = sig
     type t