diff --git a/README.md b/README.md
index 263d405..24aa15c 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,11 @@ pub enum DataStoreError {
 
 ## Details
 
+- Thiserror deliberately does not appear in your public API. You get the same
+  thing as if you had written an implementation of `std::error::Error` by hand,
+  and switching from handwritten impls to thiserror or vice versa is not a
+  breaking change.
+
 - Errors may be enums, structs with named fields, tuple structs, or unit
   structs.
 
diff --git a/src/lib.rs b/src/lib.rs
index c65e360..ec78b84 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -31,6 +31,11 @@
 //!
 //! # Details
 //!
+//! - Thiserror deliberately does not appear in your public API. You get the
+//!   same thing as if you had written an implementation of `std::error::Error`
+//!   by hand, and switching from handwritten impls to thiserror or vice versa
+//!   is not a breaking change.
+//!
 //! - Errors may be enums, structs with named fields, tuple structs, or unit
 //!   structs.
 //!