diff --git a/src/linkahead/common/models.py b/src/linkahead/common/models.py
index 65b945cebca9e33a81043992f460949d056f29f1..abcf0b2da57398a318b092cabd70bee1af1b790c 100644
--- a/src/linkahead/common/models.py
+++ b/src/linkahead/common/models.py
@@ -1453,6 +1453,9 @@ out: List[Entity]
     def update_acl(self, **kwargs):
         """Update this entity's ACL on the server.
 
+        A typical workflow is to first edit ``self.acl`` and then call this
+        method.
+
         Note
         ----
         This overwrites any existing ACL, so you may want to run
@@ -1461,8 +1464,9 @@ out: List[Entity]
         Parameters
         ----------
         **kwargs : dict
-            Keyword arguments that are being passed through to the
-            ``Entity.update`` method.
+            Keyword arguments that are passed through to the
+            ``Entity.update`` method.  Useful for e.g. ``unique=False`` in the
+            case of naming collisions.
 
         Returns
         -------