diff --git a/zebra-state/src/config.rs b/zebra-state/src/config.rs
index d5f0d93f..e8441709 100644
--- a/zebra-state/src/config.rs
+++ b/zebra-state/src/config.rs
@@ -15,28 +15,41 @@ pub struct Config {
     /// include private data that cannot be replicated from the network, such as
     /// wallet data.  That data is not handled by `zebra-state`.
     ///
-    /// Each network has a separate state, which is stored in "mainnet/state"
-    /// and "testnet/state" subdirectories.
+    /// Each state format version and network has a separate state.
+    /// These states are stored in `state/vN/mainnet` and `state/vN/testnet` subdirectories,
+    /// underneath the `cache_dir` path, where `N` is the state format version.
+    ///
+    /// When Zebra's state format changes, it creates a new state subdirectory for that version,
+    /// and re-syncs from genesis.
+    ///
+    /// Old state versions are [not automatically deleted](https://github.com/ZcashFoundation/zebra/issues/1213).
+    /// It is ok to manually delete old state versions.
+    ///
+    /// It is also ok to delete the entire cached state directory.
+    /// If you do, Zebra will re-sync from genesis next time it is launched.
     ///
     /// The default directory is platform dependent, based on
     /// [`dirs::cache_dir()`](https://docs.rs/dirs/3.0.1/dirs/fn.cache_dir.html):
     ///
-    /// |Platform | Value                                           | Example                            |
-    /// | ------- | ----------------------------------------------- | ---------------------------------- |
-    /// | Linux   | `$XDG_CACHE_HOME/zebra` or `$HOME/.cache/zebra` | /home/alice/.cache/zebra           |
-    /// | macOS   | `$HOME/Library/Caches/zebra`                    | /Users/Alice/Library/Caches/zebra  |
-    /// | Windows | `{FOLDERID_LocalAppData}\zebra`                 | C:\Users\Alice\AppData\Local\zebra |
-    /// | Other   | `std::env::current_dir()/cache`                 |                                    |
+    /// |Platform | Value                                           | Example                              |
+    /// | ------- | ----------------------------------------------- | ------------------------------------ |
+    /// | Linux   | `$XDG_CACHE_HOME/zebra` or `$HOME/.cache/zebra` | `/home/alice/.cache/zebra`           |
+    /// | macOS   | `$HOME/Library/Caches/zebra`                    | `/Users/Alice/Library/Caches/zebra`  |
+    /// | Windows | `{FOLDERID_LocalAppData}\zebra`                 | `C:\Users\Alice\AppData\Local\zebra` |
+    /// | Other   | `std::env::current_dir()/cache/zebra`           | `/cache/zebra`                       |
     pub cache_dir: PathBuf,
 
     /// Whether to use an ephemeral database.
     ///
-    /// Ephemeral databases are stored in a temporary directory.
+    /// Ephemeral databases are stored in a temporary directory created using [`tempfile::tempdir()`].
     /// They are deleted when Zebra exits successfully.
     /// (If Zebra panics or crashes, the ephemeral database won't be deleted.)
     ///
     /// Set to `false` by default. If this is set to `true`, [`cache_dir`] is ignored.
     ///
+    /// Ephemeral directories are created in the [`std::env::temp_dir()`].
+    /// Zebra names each directory after the state version and network, for example: `zebra-state-v21-mainnet-XnyGnE`.
+    ///
     /// [`cache_dir`]: struct.Config.html#structfield.cache_dir
     pub ephemeral: bool,
 
@@ -64,7 +77,7 @@ impl Config {
 
         if self.ephemeral {
             gen_temp_path(&format!(
-                "zebra-state-v{}-{}",
+                "zebra-state-v{}-{}-",
                 crate::constants::DATABASE_FORMAT_VERSION,
                 net_dir
             ))