diff --git a/README.md b/README.md
index 387a56e..17ed47e 100644
--- a/README.md
+++ b/README.md
@@ -165,6 +165,27 @@ pub enum DataStoreError {
   }
   ```
 
+  Another use case is hiding implementation details of an error representation
+  behind an opaque error type, so that the representation is able to evolve
+  without breaking the crate's public API.
+
+  ```rust
+  // PublicError is public, but opaque and easy to keep compatible.
+  #[derive(Error, Debug)]
+  #[error(transparent)]
+  pub struct PublicError(#[from] ErrorRepr);
+
+  impl PublicError {
+      // Accessors for anything we do want to expose publicly.
+  }
+
+  // Private and free to change across minor version of the crate.
+  #[derive(Error, Debug)]
+  enum ErrorRepr {
+      ...
+  }
+  ```
+
 - See also the [`anyhow`] library for a convenient single error type to use in
   application code.
 
diff --git a/src/lib.rs b/src/lib.rs
index 4b4ce9b..8f122a0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -202,6 +202,7 @@
 //!
 //!   ```
 //!   # use thiserror::Error;
+//!   #
 //!   // PublicError is public, but opaque and easy to keep compatible.
 //!   #[derive(Error, Debug)]
 //!   #[error(transparent)]