diff --git a/object_store/src/buffered.rs b/object_store/src/buffered.rs
index fdefe599f79e..9299e1147bc1 100644
--- a/object_store/src/buffered.rs
+++ b/object_store/src/buffered.rs
@@ -207,6 +207,10 @@ impl AsyncBufRead for BufReader {
 
 /// An async buffered writer compatible with the tokio IO traits
 ///
+/// This writer adaptively uses [`ObjectStore::put`] or
+/// [`ObjectStore::put_multipart`] depending on the amount of data that has
+/// been written.
+///
 /// Up to `capacity` bytes will be buffered in memory, and flushed on shutdown
 /// using [`ObjectStore::put`]. If `capacity` is exceeded, data will instead be
 /// streamed using [`ObjectStore::put_multipart`]
@@ -255,7 +259,8 @@ impl BufWriter {
         }
     }
 
-    /// Returns the [`MultipartId`] if multipart upload
+    /// Returns the [`MultipartId`] of the multipart upload created by this
+    /// writer, if any.
     pub fn multipart_id(&self) -> Option<&MultipartId> {
         self.multipart_id.as_ref()
     }
diff --git a/object_store/src/lib.rs b/object_store/src/lib.rs
index 8132002b6e01..4960f3ba390a 100644
--- a/object_store/src/lib.rs
+++ b/object_store/src/lib.rs
@@ -88,11 +88,11 @@
 //!
 //! # Why not a Filesystem Interface?
 //!
-//! Whilst this crate does provide a [`BufReader`], the [`ObjectStore`] interface mirrors the APIs
-//! of object stores and not filesystems, opting to provide stateless APIs instead of the cursor
-//! based interfaces such as [`Read`] or [`Seek`] favoured by filesystems.
+//! The [`ObjectStore`] interface is designed to mirror the APIs
+//! of object stores and *not* filesystems, and thus has stateless APIs instead
+//! of cursor based interfaces such as [`Read`] or [`Seek`] available in filesystems.
 //!
-//! This provides some compelling advantages:
+//! This design provides the following advantages:
 //!
 //! * All operations are atomic, and readers cannot observe partial and/or failed writes
 //! * Methods map directly to object store APIs, providing both efficiency and predictability
@@ -100,7 +100,12 @@
 //! * Allows for functionality not native to filesystems, such as operation preconditions
 //! and atomic multipart uploads
 //!
+//! This crate does provide [`BufReader`] and [`BufWriter`] adapters
+//! which provide a more filesystem-like API for working with the
+//! [`ObjectStore`] trait, however, they should be used with care
+//!
 //! [`BufReader`]: buffered::BufReader
+//! [`BufWriter`]: buffered::BufWriter
 //!
 //! # Adapters
 //!