diff --git a/docs/reference/pins/map.md b/docs/reference/pins/map.md
index 5e7ea593..04c152b7 100644
--- a/docs/reference/pins/map.md
+++ b/docs/reference/pins/map.md
@@ -1,8 +1,14 @@
 # Map
 
-Re-maps a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.
+Remaps the specified value from one range to another. This function
+maps the value of ``from low`` to the value of ``to low``, the value
+of ``from high`` to the value of ``to high``, and intermediate values
+to intermediate values.
 
-Does not constrain values to within the range, because out-of-range values are sometimes intended and useful. The `math->clamp` function may be used either before or after this function, if limits to the ranges are desired.
+This function does not constrain values to the ranges, because
+out-of-range values are sometimes intended and useful.  If you need to
+limit a range, you can use the ``Math.clamp`` function before or after
+calling this function.
 
 ```sig
 pins.map(0, 0, 4, 0, 1023);
@@ -10,15 +16,16 @@ pins.map(0, 0, 4, 0, 1023);
 
 ### Parameters
 
-* ``value``: [Number](/reference/types/number) - the value to map
-* ``from low``: [Number](/reference/types/number)  - lower bound of the origin interval
-* ``from high``: [Number](/reference/types/number)  - upper bound of the origin interval
-* ``to low``: [Number](/reference/types/number)  - lower bound of the target interval
-* ``to high``: [Number](/reference/types/number)  - upper bound of the target interval
+* ``value``: a [number](/reference/types/number) that specifies the value to map
+* ``from low``: a [number](/reference/types/number)  that specifies the lower bound of the origin interval
+* ``from high``: a [number](/reference/types/number)  that specifies the upper bound of the origin interval
+* ``to low``: a [number](/reference/types/number)  that specifies the lower bound of the target interval
+* ``to high``: a [number](/reference/types/number)  that specifies the upper bound of the target interval
 
 ## Example
 
-Map the value read from the analog pin ``P0`` to an LED index between ``0`` and ``4``.
+This example maps the value read from the analog pin `P0` to an LED
+coordinate between `0` and `4`.
 
 ```blocks
 let value1 = pins.analogReadPin(AnalogPin.P0)