diff --git a/docs/reference/pins/analog-read-pin.md b/docs/reference/pins/analog-read-pin.md
index fceccfe0..45e9bd3c 100644
--- a/docs/reference/pins/analog-read-pin.md
+++ b/docs/reference/pins/analog-read-pin.md
@@ -9,7 +9,7 @@ pins.analogReadPin(AnalogPin.P0)
 
 ### Parameters
 
-* a [string](/reference/types/string) that stores the name of the pin
+* a [string](/reference/types/string) with the name of the pin
   you say (`P0` through `P4`, or `P10`)
 
 ### Returns
@@ -26,6 +26,14 @@ basic.forever(() => {
 });
 ```
 
+#### ~hint
+
+If you are using **analog read pin** with another micro:bit
+running **analog write pin**, it is a good idea to check
+**analog read pin** many times and then take an average.
+
+#### ~
+
 ### See also
 
 [micro:bit pins](/device/pins),
diff --git a/docs/reference/pins/analog-write-pin.md b/docs/reference/pins/analog-write-pin.md
index 291fdcba..3c4d3f1a 100644
--- a/docs/reference/pins/analog-write-pin.md
+++ b/docs/reference/pins/analog-write-pin.md
@@ -1,6 +1,7 @@
 # Analog Write Pin
 
-Write to the specified [pin](/device/pins) (P0, P1, P2) as analog.
+Write an **analog** signal (`0` through `1023`) to the
+[pin](/device/pins) you say.
 
 ```sig
 pins.analogWritePin(AnalogPin.P0, 400)
@@ -8,15 +9,25 @@ pins.analogWritePin(AnalogPin.P0, 400)
 
 ### Parameters
 
-* `name` - [String](/reference/types/string); the pin name ("P0", "P1", or "P2")
-* `value` - a [Number](/reference/types/number) between 0 and 1023 included
+* a [string](/reference/types/string) that is the pin name you say (`P0` through `P4`, or `P10`)
+* a [number](/reference/types/number) from `0` through `1023`
 
-The following code writes `1023` to the `P0` pin:
+### Example
+
+This program writes `1023` to pin `P0`.
 
 ```blocks
 pins.analogWritePin(AnalogPin.P0, 1023)
 ```
 
+#### ~hint
+
+When you tell it to write `256` (for example), this function does not
+_really_ write `256`.  Instead, it writes a lot of different numbers,
+and their average is `256`.
+
+#### ~
+
 ### See also
 
 [micro:bit pins](/device/pins), [on pin pressed](/reference/input/on-pin-pressed), [analog read pin](/reference/pins/analog-read-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)