diff --git a/artiq/language/environment.py b/artiq/language/environment.py
index 62dae4803..efab7a01a 100644
--- a/artiq/language/environment.py
+++ b/artiq/language/environment.py
@@ -88,10 +88,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 f674d0433..5c149b3e1 100644
--- a/artiq/language/scan.py
+++ b/artiq/language/scan.py
@@ -143,6 +143,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 default: The default scan object. This parameter can be a list of
         scan objects, in which case the first one is used as default and the
         others are used to configure the default values of scan types that are
@@ -155,9 +158,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,