diff --git a/docs/source/rbac/scopes.md b/docs/source/rbac/scopes.md
index 6ec0141b..f8102303 100644
--- a/docs/source/rbac/scopes.md
+++ b/docs/source/rbac/scopes.md
@@ -160,7 +160,7 @@ c.JupyterHub.load_roles = [
         "groups": ["graders"],
         "scopes": [
             "custom:myservice:read",
-            access:service!service=myservice,
+            "access:service!service=myservice",
         ],
     },
     # instructors have read and write access to the service
@@ -169,7 +169,7 @@ c.JupyterHub.load_roles = [
         "groups": ["instructors"],
         "scopes": [
             "custom:myservice:write",
-            access:service!service=myservice,
+            "access:service!service=myservice",
         ],
     },
 ]
diff --git a/jupyterhub/app.py b/jupyterhub/app.py
index 6d93ec9d..ddb9649a 100644
--- a/jupyterhub/app.py
+++ b/jupyterhub/app.py
@@ -2039,7 +2039,7 @@ class JupyterHub(Application):
         db.commit()
 
     async def init_role_creation(self):
-        """Load default and user-defined roles into the database"""
+        """Load default and user-defined roles and scopes into the database"""
         if self.custom_scopes:
             self.log.info(f"Defining {len(self.custom_scopes)} custom scopes.")
             scopes.define_custom_scopes(self.custom_scopes)
diff --git a/jupyterhub/scopes.py b/jupyterhub/scopes.py
index 51ee6c23..7a34f122 100644
--- a/jupyterhub/scopes.py
+++ b/jupyterhub/scopes.py
@@ -652,6 +652,8 @@ Scopes may not end with a hyphen or colon.
 def define_custom_scopes(scopes):
     """Define custom scopes
 
+    Adds custom scopes to the scope_definitions dict.
+
     Scopes must start with `custom:`.
     It is recommended to name custom scopes with a pattern like::
 
@@ -663,7 +665,8 @@ def define_custom_scopes(scopes):
 
     That makes them easy to parse and avoids collisions across projects.
 
-    All scopes must have at least a `definition`,
+    `scopes` must have at least one scope definition,
+    and each scope definition must have a `description`,
     which will be displayed on the oauth authorization page,
     and _may_ have a `subscopes` list of other scopes if having one scope
     should imply having other, more specific scopes.
@@ -673,7 +676,7 @@ def define_custom_scopes(scopes):
     scopes: dict
         A dictionary of scope definitions.
         The keys are the scopes,
-        while the values are dictionaries with at least a `definition` field,
+        while the values are dictionaries with at least a `description` field,
         and optional `subscopes` field.
         %s
     Examples::