diff --git a/kinto/core/resource/__init__.py b/kinto/core/resource/__init__.py
index 8626d1557..c07056f6c 100644
--- a/kinto/core/resource/__init__.py
+++ b/kinto/core/resource/__init__.py
@@ -137,7 +137,19 @@ def callback(context, name, ob):
 
 
 class UserResource:
-    """Base resource class providing every endpoint."""
+    """Base resource class providing every endpoint.
+
+    Resources inheriting from UserResource are automatically "scoped"
+    by user (see get_parent_id()), with the effect that one user
+    cannot look at another user's data. This is good for implementing
+    sensitive or private information such as accounts.
+
+    However, most resources in Kinto can be shared by different users,
+    with different levels of access determined by their
+    permissions. Those resources should inherit from
+    ShareableResource, below.
+
+    """
 
     default_viewset = ViewSet
     """Default :class:`kinto.core.resource.viewset.ViewSet` class to use when
diff --git a/kinto/core/storage/__init__.py b/kinto/core/storage/__init__.py
index 3df5bd103..6668140f3 100644
--- a/kinto/core/storage/__init__.py
+++ b/kinto/core/storage/__init__.py
@@ -250,7 +250,11 @@ def get_all(self, collection_id, parent_id, filters=None, sorting=None,
         """Retrieve all objects in this `collection_id` for this `parent_id`.
 
         :param str collection_id: the collection id.
-        :param str parent_id: the collection parent.
+
+        :param str parent_id: the collection parent, possibly
+            containing a wildcard '*'. (This can happen when
+            implementing "administrator" operations on a UserResource,
+            for example.)
 
         :param filters: Optionally filter the objects by their attribute.
             Each filter in this list is a tuple of a field, a value and a