diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index a138dee4128..9d83c5e4207 100644
--- a/doc/whats-new.rst
+++ b/doc/whats-new.rst
@@ -46,6 +46,10 @@ Bug fixes
 
 Documentation
 ~~~~~~~~~~~~~
+- update the docstring of :py:meth:`Dataset.diff` and
+  :py:meth:`DataArray.diff` so it does document the ``dim``
+  parameter as required. (:issue:`1040`, :pull:`3909`)
+  By `Justus Magin <https://github.com/keewis>`_.
 
 
 Internal Changes
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index 070886cfc34..94c4026d4a1 100644
--- a/xarray/core/dataarray.py
+++ b/xarray/core/dataarray.py
@@ -2696,7 +2696,7 @@ def diff(self, dim: Hashable, n: int = 1, label: Hashable = "upper") -> "DataArr
 
         Parameters
         ----------
-        dim : hashable, optional
+        dim : hashable
             Dimension over which to calculate the finite difference.
         n : int, optional
             The number of times values are differenced.
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index c49694b1fc0..bd8f0ef3948 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -4901,7 +4901,7 @@ def diff(self, dim, n=1, label="upper"):
 
         Parameters
         ----------
-        dim : str, optional
+        dim : str
             Dimension over which to calculate the finite difference.
         n : int, optional
             The number of times values are differenced.