diff --git a/artiq/language/environment.py b/artiq/language/environment.py
index 80ce8c877..3a2d9164c 100644
--- a/artiq/language/environment.py
+++ b/artiq/language/environment.py
@@ -85,10 +85,16 @@ class NumberValue(_SimpleArgProcessor):
     The simplest way to represent an integer argument is
     ``NumberValue(step=1, ndecimals=0)``.
 
-    :param unit: A string representing the unit of the value, for user
-        interface (UI) purposes.
-    :param scale: The scale of value for UI purposes. The displayed value is
-        divided by the scale.
+    For arguments with units, use both the unit parameter (a string for
+    display) and the scale parameter (a numerical scale for experiments).
+    For example, ``NumberValue(1, unit="ms", scale=1*ms)`` will display as
+    1 ms in the GUI window because of the unit setting, and appear as the
+    numerical value 0.001 in the code because of the scale setting.
+
+    :param unit: A string representing the unit of the value, for display
+        purposes only.
+    :param scale: A numerical scaling factor by which the displayed value is
+        multiplied when referenced in the experiment.
     :param step: The step with which the value should be modified by up/down
         buttons in a UI. The default is the scale divided by 10.
     :param min: The minimum value of the argument.
diff --git a/artiq/language/scan.py b/artiq/language/scan.py
index 7ead27f62..a60bebeb2 100644
--- a/artiq/language/scan.py
+++ b/artiq/language/scan.py
@@ -141,6 +141,9 @@ class Scannable:
     """An argument (as defined in :class:`artiq.language.environment`) that
     takes a scan object.
 
+    For arguments with units, use both the unit parameter (a string for
+    display) and the scale parameter (a numerical scale for experiments).
+
     :param global_min: The minimum value taken by the scanned variable, common
         to all scan modes. The user interface takes this value to set the
         range of its input widgets.
@@ -149,9 +152,9 @@ class Scannable:
         up/down buttons in a user interface. The default is the scale divided
         by 10.
     :param unit: A string representing the unit of the scanned variable, for
-        user interface (UI) purposes.
-    :param scale: The scale of value for UI purposes. The displayed value is
-        divided by the scale.
+        display purposes only.
+    :param scale: A numerical scaling factor by which the displayed values
+        are multiplied when referenced in the experiment.
     :param ndecimals: The number of decimals a UI should use.
     """
     def __init__(self, default=NoDefault, unit="", scale=1.0,