Add some descriptive info to serial docs (#704)

* Local commit

* Add some descriptive info to serial docs

* Example typo

* Tiny edit

docs/reference/serial/write-numbers.md

@@ -6,9 +6,17 @@ Write an array of numbers to the [serial](/device/serial) port.
 serial.writeNumbers([0, 1, 2]);
 ```
 
+Instead of writing a single number at a time using [write number](/reference/serial/write-number), you can write multiple numbers to the serial port at once. They are written as _Comma Separated Values (CSV)_.
+
+You can write the numbers `0` through `5` together and they will appear as one line of serial output:
+
+``0,1,2,3,4,5``
+
+This makes a line of CSV data where the commas between the numbers are the separators for each value.
+
 ## Parameters
 
-* `values` is the array of [number](/types/number) to write to the serial port
+* `values`: the array of [numbers](/types/number) to write to the serial port
 
 ## Example: one two three
 
@@ -23,7 +31,6 @@ basic.forever(() => {
 
 ## Example: plot temperature and light
 
-
 ```blocks
 serial.writeLine("temp,light")
 basic.forever(() => {
@@ -36,4 +43,3 @@ basic.forever(() => {
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),
 [serial write value](/reference/serial/write-value)
-

docs/reference/serial/write-value.md

@@ -1,19 +1,30 @@
-# Write Value
+# write Value
 
-Write a name/value pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
+Write a **name:value** pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
 
 ```sig
 serial.writeValue("x", 0);
 ```
 
+It is common when reporting or recording data to use a _Name Value Pair_ (NVP). They appear as a text output string in the form of a _name_ and a _value_ together. The name and the value are separated in the string with a _colon_, `:`. A name value pair reporting a temperature of `-15` degrees could look like:
+
+``temperature:-15``
+
+Associating a name with a value helps to identify related data when different data sources are recorded. For example, if you're reporting both temperature and light intensity, the _name:value_ format helps spreadsheets or other data analysis programs distingush between them and group the same types of values together properly. Reporting two data sources might look like this in the output:
+
+```
+temperature:-15
+temperature:-12
+light:154
+temperature:-11
+light:152
+```
+
 ## Parameters
 
 * `name` is the [string](/types/string) to write to the serial port
 * `value` is the [number](/types/number) to write to the serial port
 
-
-
-
 ## Example: streaming data
 
 Every 10 seconds, the example below sends the temperature and light level