Update variable reference pages

docs/blocks/variables/assign.md

@@ -1,11 +1,34 @@
 # Assignment Operator
 
-Use an equals sign to make a [variable](/blocks/variables/var) store the [number](/types/number) 
-or [string](/types/string) you say.
+Use an equals sign to make a [variable](/blocks/variables/var) store a [number](/types/number), [string](/types/string), or other [type](/types) of value.
 
-When you use the equals sign to store something in a variable, the equals sign is called
+When you use the equals sign (**=**) to store something in a variable, the equals sign is called
 an *assignment operator*, and what you store is called a *value*.
 
+When you work in JavaScript or Python the equals sign is used:
+
+```typescript-ignore
+item = 3
+```
+
+## The 'set' block
+
+In blocks, a variable assignment happens with the ``||variables:set||`` block when you set a value to a [variable](/blocks/variables/var).
+
+```block
+let item = 3
+```
+
+### ~ hint
+
+#### Setting a variable using the Toolbox
+
+In the ``||variables:Variables||`` category of the **Toolbox** you can create or choose a variable to assign:
+
+![Setting a variable to a value](/static/blocks/variables/assign.gif)
+
+### ~
+
 ## Storing numbers in variables
 
 This program makes the variable `item` equal `5` and then shows it on the [LED screen](/device/screen).

docs/blocks/variables/var.md

@@ -1,55 +1,77 @@
-# Local Variables
+# Declaring variables
 
-How to define and use local variables.
+How to declare and use variables.
 
 ## @parent language
 
-A variable is a place where you can store and retrieve data. Variables have a name, a [type](/types), and value:
+A variable is a place where you can store and retrieve data. Variables have a name, a [type](/types), and a value:
 
 * *name* is how you'll refer to the variable
-* *type* refers to the kind of data a variable can store
-* *value* refers to what's stored in the variable
+* *type* is the kind of data a variable can store
+* *value* is what's stored in the variable
 
-## Var statement
+## The variable (var) statement
 
-Use the Block Editor variable statement to create a variable 
-and the [assignment operator](/blocks/variables/assign) 
-to store something in the variable.
+A variable is created using a `variable` statement. The variable will "declare" itself in this statement. In MakeCode JavaScript a variable is declared along with its first [assignment](/blocks/variables/assign):
 
-For example, this code stores the number `2` in the `x` variable:
+```typescript
+let x = 2
+```
+
+With Python a variable is declared when it's first used. In this case the variable statement is just the assignment of the variable:
+
+```python
+x = 2
+```
+
+If a variable is declared in blocks you will see the ``||variables:set||`` block with the first use of the variable. This code stores the number `2` in the `x` variable:
 
 ```blocks
-let x = 2;
+let x = 2
 ```
-Here's how to define a variable in the Block Editor:
 
-1. Click `variables`.
+The new variable is created inside the ``||variables:Variables||`` category of the **Toolbox**.
+
+### ~ hint
 
-2. Change the default variable name if you like.
+#### Creating a variable from the Toolbox
 
-3. Drag a block type on the right-side of the [assignment operator](/blocks/variables/assign) and click the down arrow to change the variable name.
+In the ``||variables:Variables||`` category of the **Toolbox** you can create new variable:
+
+![Create a new variable](/static/blocks/variables/create.gif)
+
+Here's how to create a variable using the Toolbox:
+
+1. Click ``||variables:Variables||`` in the Toolbox.
+2. Click on **Make a Variable...**.
+3. Choose a name for your variable, type it in, and click **Ok**.
+4. Drag the new variable, ``||variables:set||`` or ``||variables:change||`` block into your code. 
+
+### ~
+
+### Quick example
 
 A variable is created for the number returned by the [brightness](/reference/led/brightness) function.
 
 ```blocks
-let b = led.brightness();
+let b = led.brightness()
 ```
 
 ## Using variables
 
 Once you've defined a variable, just use the variable's name whenever you need what's stored in the variable. For example, the following code shows the value stored in `counter` on the LED screen:
 
 ```blocks
-let counter = 1;
-basic.showNumber(counter);
+let counter = 1
+basic.showNumber(counter)
 ```
 
 To change the contents of a variable use the assignment operator. The following code sets `counter` to 1 and then increments `counter` by 10:
 
 ```blocks
-let counter = 1;
-counter = counter + 10;
-basic.showNumber(counter);
+let counter = 1
+counter = counter + 10
+basic.showNumber(counter)
 ```
 
 ## Why use variables?
@@ -58,11 +80,11 @@ If you want to remember and modify data, you'll need a variable.
 A counter is a great example:
 
 ```blocks
-let counter = 0;
-input.onButtonPressed(Button.A, () => { 
-  counter = counter + 1;
-  basic.showNumber(counter);
-});
+let counter = 0
+input.onButtonPressed(Button.A, function () { 
+    counter = counter + 1
+    basic.showNumber(counter)
+})
 ```
 
 ## Local variables
@@ -72,16 +94,38 @@ Local variables exist only within the function or block of code where they're de
 ```blocks
 // x does NOT exist here.
 if (led.brightness() > 128) {
-  // x exists here
-  let x = 0;
+    // x exists here
+    let x = 0
 }
 ```
 
-### Notes
+## Notes about variables
+
+### Variable names
 
-* You can use the default variable names if you'd like, however, it's best to use descriptive variable names. To change a variable name in the editor, select the down arrow next to the variable and then click "new variable".
+Some blocks come from the Toolbox with default variable names, such as `list` from ``||arrays:Arrays||``.
+You can use the default variable names if you like, however, it's best to use descriptive variable names. To change a variable name in the editor, select the down arrow next to the variable and then click **"Rename variable..."** to change it.
+
+### Hidden declaration block
+
+If a variable is used more than once, and its declaration block sets the variable to `0`, that first declaration block is hidden. For example:
+
+```blocks
+let x = 0
+if (x == 0) {
+    x = 9
+}
+```
+
+You don't see any first block setting the variable `x` to `0` but that happens in its hidden declaration statement. You'll see the declaration statement, `let x = 0`, if you switch from Blocks to JavaScript in the Editor:
+
+```typescript-ignore
+let x = 0
+if (x == 0) {
+    x = 9
+}
+```
 
 ## See also
 
 [types](/types), [assignment operator](/blocks/variables/assign)
-

docs/types/string.md

@@ -1,9 +1,27 @@
 # @extends
 
-## #intro
+## #create
 
-## ~ hint
+In the ``||variables:Variables||`` category of the **Toolbox** you can create new variable:
 
-For the @boardname@, ASCII character codes 32 to 126 are supported; letters, digits, punctuation marks, and a few symbols. All other character codes appear as a ? on the [LED screen](/device/screen).
+![Create a new string variable](/static/blocks/variables/string.gif)
 
-## ~
+Here's how to create a string variable using the Toolbox:
+
+1. Click ``||variables:Variables||`` in the Toolbox.
+2. Click on **Make a Variable...**.
+3. Choose a name for your variable, type it in, and click **Ok**.
+4. Drag the new ``||variables:set||`` block into your code.
+5. Click on the ``||text:Text||`` drawer in the Toolbox and find the ``||text:" "||`` block.
+6. Drag the ``||text:" "||`` block into the value slot in of your variable ``||variables:set||`` block.
+
+## Characters you use in strings #custom
+
+### ~ hint
+
+#### Character sets
+
+The available characters to use for a language is called the _character set_. Each character in the set has a number code to match it with.
+To display characters on the [LED screen](/device/screen), the @boardname@, uses the "ASCII" character codes of `32` to `126`; letters, digits, punctuation marks, and a few symbols. All other character codes appear as a `?` on the LED screen.
+
+### ~