Restructure language introduction around reader experience

README.md

@@ -78,6 +78,28 @@ The documentation pages are written in `.mdx` which are
 [markdown](https://www.markdownguide.org/basic-syntax/) files that can also
 import react components.
 
+## Audiences for language documentation
+
+The programmer's tour is the complete first introduction for people who already
+program. Explain Toit directly, then use C/C++, JavaScript, Python, or Java/Kotlin
+comparisons where useful. Familiarity with every comparison language is not a
+prerequisite. Keep essential content in one reading path; language-specific
+pages highlight differences and link into it. Reference pages cover detailed
+rules rather than carrying missing parts of the introduction.
+
+Beginner lessons assume no programming knowledge. Introduce concepts when a
+concrete example needs them, with time to run and modify the program before
+adding another concept. Split lessons at useful stopping points.
+
+## Examples in documentation
+
+Keep examples visible when they introduce a concept or the surrounding text
+explains them. A reader should not have to expand code to follow the argument.
+For experienced readers, state the rule concisely and show one or two examples.
+Use `<Expandable title="More examples: ...">` for supplementary collections that
+explore variations and edge cases, with output or comments explaining each case.
+Keep exercise solutions collapsed so readers can try the exercise first.
+
 ## Components
 
 There are multiple components to make the content more engaging:

docs/language/beginner.mdx

@@ -0,0 +1,205 @@
+# Beginner tutorial
+
+These lessons are for someone new to programming. You will write a temperature
+report using sample readings, so you need a computer but no sensor or ESP32.
+If you already program, start with [Toit for programmers](/language/toitversus).
+
+You should be comfortable creating a text file and opening a terminal. The
+terminal is where you type the command that runs your program. We explain the
+programming concepts as they appear.
+
+| Lesson | What you will make |
+| --- | --- |
+| 1. Your first program, on this page | Report whether one temperature is warm. |
+| [2. Lists and functions](/language/beginner/lists-and-functions) | Report several readings using one reusable operation. |
+| [3. Objects](/language/beginner/objects) | Keep a room's name and readings together. Continue here when you are ready. |
+
+Each example is a complete program. Replace the contents of your file rather
+than appending the example to the previous one. Run it after each change.
+
+## 1. Run your first program
+
+Install the [Toit SDK](https://github.com/toitlang/toit#readme), which includes
+the tools to run Toit programs. Check the installation by typing `toit --help`
+in a terminal. It should display instructions for the command.
+If you already have Jaguar installed, use `jag toit` instead of `toit` in these
+commands; you do not need to connect a device.
+
+In a text editor, create a file named `report.toit` containing these two lines:
+
+```toit
+main:
+  print "Temperature report"
+```
+
+The two spaces before `print` matter. Use spaces, not the Tab key.
+Save the file, open a terminal in the directory containing it, and type:
+
+```sh
+toit run report.toit
+```
+
+You should see:
+
+```text
+Temperature report
+```
+
+`main:` marks where the program starts. The indented line underneath it is an
+instruction: `print` displays the text between the double quotes. Text written
+this way is called a *string*. The quotes are part of the program, but are not
+printed.
+
+Change `Temperature report` to `Kitchen report`, save, and run the command
+again. The new message should appear. The program runs the saved version of
+your file, so remember to save before running.
+
+<Expandable title="If the program does not run">
+
+If the terminal cannot find `toit`, revisit the SDK installation instructions.
+If it cannot find `report.toit`, check that the terminal is open in the directory
+where you saved the file. If Toit reports a problem in the program, start with
+the first reported line. Compare the spelling, quotes, colon, and indentation
+with the example.
+
+</Expandable>
+
+## 2. Give a value a name
+
+We want the report to include a temperature. We could print `21` directly, but
+naming it lets us use the same value in several places.
+
+A *variable* is a name for a value. `temperature := 21` creates a variable named
+`temperature` with the value `21`. The `:=` introduces that new name.
+
+<!-- RESET CODE -->
+
+```toit
+main:
+  temperature := 21
+  print temperature
+```
+
+This prints `21`. There are no quotes around `temperature`: we want its value,
+not the word “temperature”. Instructions run from top to bottom, so the variable
+is created before `print` uses it.
+
+Change `21` to `24`, save, and run again. Then try `print "temperature"` and
+compare the output. Put `print temperature` back before continuing.
+
+## 3. Change the value
+
+Once a variable exists, use `=` to replace its value. Use `:=` only when
+introducing the name.
+
+<!-- RESET CODE -->
+
+```toit
+main:
+  temperature := 21
+  print temperature
+  temperature = 24
+  print temperature
+```
+
+The output is:
+
+```text
+21
+24
+```
+
+The first `print` uses the value at that point in the program. Changing the
+variable later does not change text that has already been printed.
+
+You can calculate a new value from the old one. Replace `temperature = 24`
+with `temperature = temperature + 3`. Toit first adds three to the current
+value, then stores the result. The output should stay the same.
+
+Try adding five instead. Predict the second line before running the program.
+
+## 4. Put the value in a message
+
+To print a label and a value together, put `$temperature` inside a string.
+Toit replaces it with the variable's value. This is called *interpolation*.
+
+<!-- RESET CODE -->
+
+```toit
+main:
+  temperature := 21
+  print "Temperature: $temperature C"
+```
+
+This prints:
+
+```text
+Temperature: 21 C
+```
+
+Change the value to `24`. You only need to change the line that sets the
+temperature; the message uses that value automatically.
+
+## 5. Decide what to print
+
+Our program should say “Warm” when the temperature is at least 25 degrees.
+Otherwise, it should say “Comfortable”. The question “is this temperature at
+least 25?” is written as `temperature >= 25`.
+
+<!-- RESET CODE -->
+
+```toit
+main:
+  temperature := 24
+  print "Temperature: $temperature C"
+  if temperature >= 25:
+    print "Warm"
+  else:
+    print "Comfortable"
+```
+
+This prints:
+
+```text
+Temperature: 24 C
+Comfortable
+```
+
+`if` asks the question. When the answer is yes, the program runs the further
+indented instruction below it. When the answer is no, it runs the instruction
+below `else:` instead. Only one of the two messages is printed.
+
+The comparison is called a *condition*. Its result is `true` for yes or `false`
+for no. Those two values are called *booleans*.
+
+Try temperatures of `25` and `30`. Both should print `Warm`. Try `20`, which
+should print `Comfortable`. You have now checked values below, at, and above
+the threshold.
+
+## Practice before continuing
+
+Change the report so that it describes a freezer: print `Freezing` when the
+temperature is below zero, and `Not freezing` otherwise. Use `<` for “less than”.
+Check the program with `-5`, `0`, and `5`.
+
+<Expandable title="Solution: check for freezing temperatures">
+
+<!-- RESET CODE -->
+
+```toit
+main:
+  temperature := -5
+  if temperature < 0:
+    print "Freezing"
+  else:
+    print "Not freezing"
+```
+
+This prints `Freezing`. With `0` or `5`, it prints `Not freezing`.
+
+</Expandable>
+
+You have a complete program that stores a reading, includes it in a message,
+and chooses a description. Continue with
+[lists and functions](/language/beginner/lists-and-functions) to report several
+readings without copying the same instructions for each one.