docs: clarify difference between load and open in docstrings

changes/3984.doc.md

@@ -0,0 +1,4 @@
+Clarify the difference between `zarr.load` and `zarr.open` in their docstrings.
+`load` eagerly reads data into an in-memory NumPy array, while `open` returns a
+lazy `Array` or `Group` backed by the store, with `See Also` cross-references
+linking the two.

src/zarr/api/asynchronous.py

@@ -294,12 +294,18 @@ async def load(
 
     See Also
     --------
-    save
+    save, open
 
     Notes
     -----
     If loading data from a group of arrays, data will not be immediately loaded into
     memory. Rather, arrays will be loaded into memory as they are requested.
+
+    Unlike [`open`][zarr.open], which returns a lazy [`Array`][zarr.Array] or
+    [`Group`][zarr.Group] backed by the store, `load` eagerly reads the data and
+    returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group).
+    Use `open` when you want to read or write data incrementally without loading it
+    all into memory.
     """
 
     obj = await open(store=store, path=path, zarr_format=zarr_format)
@@ -347,6 +353,16 @@ async def open(
     -------
     z : array or group
         Return type depends on what exists in the given store.
+
+    See Also
+    --------
+    load
+
+    Notes
+    -----
+    `open` returns a lazy [`Array`][zarr.Array] or [`Group`][zarr.Group] backed by
+    the store, so data is read and written incrementally. Use [`load`][zarr.load]
+    instead when you want the data eagerly read into an in-memory NumPy array.
     """
 
     if mode is None:

src/zarr/api/synchronous.py

@@ -161,12 +161,18 @@ def load(
 
     See Also
     --------
-    save, savez
+    save, savez, open
 
     Notes
     -----
     If loading data from a group of arrays, data will not be immediately loaded into
     memory. Rather, arrays will be loaded into memory as they are requested.
+
+    Unlike [`open`][zarr.open], which returns a lazy [`Array`][zarr.Array] or
+    [`Group`][zarr.Group] backed by the store, `load` eagerly reads the data and
+    returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group).
+    Use `open` when you want to read or write data incrementally without loading it
+    all into memory.
     """
     return sync(async_api.load(store=store, zarr_format=zarr_format, path=path))
 
@@ -209,6 +215,16 @@ def open(
     -------
     z : array or group
         Return type depends on what exists in the given store.
+
+    See Also
+    --------
+    load
+
+    Notes
+    -----
+    `open` returns a lazy [`Array`][zarr.Array] or [`Group`][zarr.Group] backed by
+    the store, so data is read and written incrementally. Use [`load`][zarr.load]
+    instead when you want the data eagerly read into an in-memory NumPy array.
     """
     obj = sync(
         async_api.open(