diff --git a/ckan/logic/action/update.py b/ckan/logic/action/update.py
index a0b80db7c6e..e60504d9b2d 100644
--- a/ckan/logic/action/update.py
+++ b/ckan/logic/action/update.py
@@ -242,13 +242,15 @@ def package_update(context, data_dict):
     '''Update a dataset (package).
 
     You must be authorized to edit the dataset and the groups that it belongs
-    to.
+    to. It is recommended to call
+    :py:func:`ckan.logic.action.get.package_show`, make the desired changes to
+    the result, and then call ``package_update()`` with it.
 
     Plugins may change the parameters of this function depending on the value
     of the dataset's ``type`` attribute, see the ``IDatasetForm`` plugin
     interface.
 
-    For further parameters see ``package_create()``.
+    For further parameters see :py:func:`ckan.logic.action.create.package_create()`.
 
     :param id: the name or id of the dataset to update
     :type id: string