DOCS: Clarify what mode means in docstring for to_zarr

xarray/core/dataarray.py

@@ -4343,14 +4343,20 @@ def to_zarr(
             Store or path to directory in local or remote file system only for Zarr
             array chunks. Requires zarr-python v2.4.0 or later.
         mode : {"w", "w-", "a", "a-", r+", None}, optional
-            Persistence mode: "w" means create (overwrite if exists);
+            Persistence mode:
+            "w" means create (remove old if exists and write new);
             "w-" means create (fail if exists);
             "a" means override all existing variables including dimension coordinates (create if does not exist);
             "a-" means only append those variables that have ``append_dim``.
             "r+" means modify existing array *values* only (raise an error if
             any metadata or shapes would change).
             The default mode is "a" if ``append_dim`` is set. Otherwise, it is
             "r+" if ``region`` is set and ``w-`` otherwise.
+
+            .. note::
+                When modifying an existing Zarr array that is lazily opened, the "w"
+                behavior can be surprising since the underlying file that is being
+                lazily read from might get deleted before the data is computed.
         synchronizer : object, optional
             Zarr array synchronizer.
         group : str, optional

xarray/core/dataset.py

@@ -2228,14 +2228,20 @@ def to_zarr(
             Store or path to directory in local or remote file system only for Zarr
             array chunks. Requires zarr-python v2.4.0 or later.
         mode : {"w", "w-", "a", "a-", r+", None}, optional
-            Persistence mode: "w" means create (overwrite if exists);
+            Persistence mode:
+            "w" means create (remove old if exists and write new);
             "w-" means create (fail if exists);
             "a" means override all existing variables including dimension coordinates (create if does not exist);
             "a-" means only append those variables that have ``append_dim``.
             "r+" means modify existing array *values* only (raise an error if
             any metadata or shapes would change).
             The default mode is "a" if ``append_dim`` is set. Otherwise, it is
             "r+" if ``region`` is set and ``w-`` otherwise.
+
+            .. note::
+                When modifying an existing Zarr array that is lazily opened, the "w"
+                behavior can be surprising since the underlying file that is being
+                lazily read from might get deleted before the data is computed.
         synchronizer : object, optional
             Zarr array synchronizer.
         group : str, optional

xarray/core/datatree.py

@@ -2122,10 +2122,18 @@ def to_zarr(
         store : zarr.storage.StoreLike
             Store or path to directory in file system
         mode : {{"w", "w-", "a", "r+", None}, default: "w-"
-            Persistence mode: “w” means create (overwrite if exists); “w-” means create (fail if exists);
-            “a” means override existing variables (create if does not exist); “r+” means modify existing
-            array values only (raise an error if any metadata or shapes would change). The default mode
-            is “w-”.
+            Persistence mode:
+            "w" means create (remove old if exists and write new);
+            "w-" means create (fail if exists);
+            "a" means override all existing variables including dimension coordinates (create if does not exist);
+            "r+" means modify existing array *values* only (raise an error if
+            any metadata or shapes would change).
+            The default mode is “w-”.
+
+            .. note::
+                When modifying an existing Zarr array that is lazily opened, the "w"
+                behavior can be surprising since the underlying file that is being
+                lazily read from might get deleted before the data is computed.
         encoding : dict, optional
             Nested dictionary with variable names as keys and dictionaries of
             variable specific encodings as values, e.g.,