From 764505d2ca6f9b82844200a11aea8816bd73f545 Mon Sep 17 00:00:00 2001
From: Ron Hale-Evans <rwhe@ludism.org>
Date: Tue, 14 Jun 2016 12:51:21 -0700
Subject: [PATCH] Rewrite in simple language. Improve code examples.

---
 docs/reference/led/brightness.md     | 14 ++++++++++++++
 docs/reference/led/set-brightness.md | 11 +++++++----
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/reference/led/brightness.md b/docs/reference/led/brightness.md
index c4f175c8..1772fead 100644
--- a/docs/reference/led/brightness.md
+++ b/docs/reference/led/brightness.md
@@ -20,6 +20,20 @@ if (led.brightness() < 255) {
 }
 ```
 
+
+### Example: change brightness
+
+This program makes the screen brightness 100% (255).  Then it turns on
+the center LED (`2, 2`), waits for one second and then sets the screen
+brightness to 50% (128):
+
+```blocks
+led.setBrightness(255)
+led.plot(2, 2)
+basic.pause(1000)
+led.setBrightness(led.brightness() / 2)
+```
+
 ### See also
 
 [set brightness](/reference/led/set-brightness), [fade in](/reference/led/fade-in), [fade out](/reference/led/fade-out)
diff --git a/docs/reference/led/set-brightness.md b/docs/reference/led/set-brightness.md
index b9262723..3525ff83 100644
--- a/docs/reference/led/set-brightness.md
+++ b/docs/reference/led/set-brightness.md
@@ -1,6 +1,7 @@
 # Set Brightness
 
-Sets the brightness of the [LED screen](/device/screen).
+Make the [LED screen](/device/screen) as bright as you say when it is
+turned on.
 
 ```sig
 led.setBrightness(121)
@@ -8,17 +9,19 @@ led.setBrightness(121)
 
 ### Parameters
 
-* value : [Number](/reference/types/number) - the brightness of the LED screen expressed as a number between 0 and 255
+* a [number](/reference/types/number) that means how bright the screen is when it is turned on, from `0` (darkest) to `255` (brightest). For example, the number `127` means the screen is halfway bright when it is turned on.
 
 ### Example: change brightness
 
-The following example sets the screen brightness to 100% (255), turns on LED `2, 2`, waits for a second and then sets the screen brightness to 50% (127):
+This program makes the screen brightness 100% (255).  Then it turns on
+the center LED (`2, 2`), waits for one second, and then sets the screen
+brightness to 50% (128):
 
 ```blocks
 led.setBrightness(255)
 led.plot(2, 2)
 basic.pause(1000)
-led.setBrightness(127)
+led.setBrightness(led.brightness() / 2)
 ```
 
 ### See also