diff --git a/doc/source/administrator/advanced.md b/doc/source/administrator/advanced.md
index 4ce7ba344e..114929ff62 100644
--- a/doc/source/administrator/advanced.md
+++ b/doc/source/administrator/advanced.md
@@ -88,40 +88,24 @@ There are four properties you can set in your `config.yaml` to do this.
 
 ### `hub.extraConfig`
 
-The value specified for `hub.extraConfig` is evaluated as python code at the end
-of `jupyterhub_config.py`. You can do anything here since it is arbitrary Python
-Code. Some examples of things you can do:
+The value specified for `hub.extraConfig` is evaluated as Python code at the end
+of a `jupyterhub_config.py` file JupyterHub loads. You can do anything in
+`hub.extraConfig` since it is arbitrary Python code, while
+[`hub.config`](schema_hub.config) only allow you to specify fixed configuration
+values.
+
+Some examples of things you can do:
 
 1. Override various methods in the Spawner / Authenticator by subclassing them.
    For example, you can use this to pass authentication credentials for the user
-   (such as GitHub OAuth tokens) to the environment. See
-   [the JupyterHub docs](https://jupyterhub.readthedocs.io/en/latest/reference/authenticators.html#authentication-state) for
-   an example.
+   (such as GitHub OAuth tokens) to the environment.
 2. Specify traitlets that take callables as values, allowing dynamic per-user
    configuration.
 3. Set traitlets for JupyterHub / Spawner / Authenticator that are not currently
-   supported in the helm chart
-
-Unfortunately, you have to write your python _in_ your YAML file. There's no way
-to include a file in `config.yaml`.
-
-You can specify `hub.extraConfig` as a raw string (remember to use the `|` for multi-line
-YAML strings):
-
-```yaml
-hub:
-  extraConfig: |
-    import time
-    c.KubeSpawner.environment.update(
-        {
-            "CURRENT_TIME": str(time.time())
-        }
-    )
-```
+   supported in the Helm chart.
 
-You can also specify `hub.extraConfig` as a dictionary, if you want to logically
-split your customizations. The code will be evaluated in alphabetical sorted
-order of the key.
+You should specify `hub.extraConfig` as a dictionary. The code will be evaluated
+in alphabetical sorted order of the key.
 
 ```yaml
 hub:
@@ -130,13 +114,16 @@ hub:
       import time
       c.KubeSpawner.environment.update(
           {
-              "CURRENT_TIME": str(time.time())
+              "JUPYTERHUB_START_TIME": str(time.time())
           }
       )
     10-second-config: |
       # some other code
 ```
 
+For more information about this configuration, see [the configuration reference
+entry about `hub.extraConfig`](schema_hub.extraConfig).
+
 ### `custom` configuration
 
 The contents of `values.yaml` is passed through to the Hub image.
diff --git a/jupyterhub/schema.yaml b/jupyterhub/schema.yaml
index 1d8a2f9ef6..3c4c60941f 100644
--- a/jupyterhub/schema.yaml
+++ b/jupyterhub/schema.yaml
@@ -834,9 +834,9 @@ properties:
           This is the *escape hatch* - if you want to configure JupyterHub to do something specific
           that is not present here as an option, you can write the raw Python to do it here.
 
-          extraConfig is a *dict*, so there can be multiple configuration snippets
-          under different names.
-          The configuration sections are run in alphabetical order.
+          extraConfig is a *dict*, so there can be multiple configuration
+          snippets under different names. The configuration sections are run in
+          alphabetical order based on the keys.
 
           Non-exhaustive examples of things you can do here:
             - Subclass authenticator / spawner to do a custom thing
@@ -848,17 +848,28 @@ properties:
           [| operator](https://yaml.org/spec/1.2/spec.html#id2795688).
 
           For example:
-            ```yaml
-            hub:
-              extraConfig:
-                myConfig.py: |
-                  c.JupyterHub.something = 'something'
-                  c.Spawner.somethingelse = 'something else'
-            ```
 
-          No validation of this python is performed! If you make a mistake here, it will probably
-          manifest as either the hub pod going into `Error` or `CrashLoopBackoff` states, or in
-          some special cases, the hub running but... just doing very random things. Be careful!
+          ```yaml
+          hub:
+            extraConfig:
+              myConfig.py: |
+                c.JupyterHub.something = 'something'
+                c.Spawner.something_else = 'something else'
+          ```
+
+          ```{note}
+          No code validation is performed until JupyterHub loads it! If you make
+          a typo here, it will probably manifest itself as the hub pod failing
+          to start up and instead entering an `Error` state or the subsequent
+          `CrashLoopBackoff` state.
+
+          To make use of your own programs linters etc, it would be useful to
+          not embed Python code inside a YAML file. To do that, consider using
+          [`hub.extraFiles`](schema_hub.extraFiles) and mounting a file to
+          `/usr/local/etc/jupyterhub/jupyterhub_config.d` in order to load your
+          extra configuration logic.
+          ```
+
       uid:
         type: [integer, "null"]
         minimum: 0