Merge pull request #6954 from roc-lang/tutorial-improvements

tutorial improvements

roc-for-elm-programmers.md

@@ -931,7 +931,7 @@ foo 1 2 if something then 3 else 4
 
 ## Backpassing
 
-Note: the backpassing syntax will likely be replaced with a new `?` operator in the future, see [this discussion](https://github.com/roc-lang/roc/issues/6828) for more details.
+Note: the backpassing syntax will likely be removed from the language. The [`!` suffix](https://www.roc-lang.org/tutorial#the-!-suffix) can instead be used for `Task.await` and the `?` suffix is [planned](https://github.com/roc-lang/roc/issues/6828) for use with `Result.try`.
 
 Suppose I'm using a platform for making a CLI, and I want to run several
 `Task`s in a row which read some files from the disk. Here's one way I could do

www/content/tutorial.md

@@ -820,18 +820,28 @@ Result.isOk (List.get ["a", "b", "c"] 1)
 ```
 
 ```roc
-Result.try (Str.toU64 "2") \idx -> List.get ["a", "b", "c", "d"] idx
-# returns `Ok "c"`
+# Running this will produce `Ok "c"`
+Result.try (Str.toU64 "2") listGet
+
+listGet : U64 -> Result Str [OutOfBounds]
+listGet = \index ->
+    List.get ["a", "b", "c", "d"] index
 
 # Notes:
 #  - `Str.toU64 "2"` parses the string "2" to the integer 2, and returns `Ok 2` (more on
 #    integer types later)
-#  - since parsing is successful, `Result.try` passes 2 to the function `\idx -> ...`
+#  - since parsing is successful, `Result.try` passes 2 to the `listGet` function
 #  - passing "abc" or "1000" instead of "2" would have resulted in `Err InvalidNumStr`
 #    or `Err OutOfBounds` respectively
 ```
 
-`Result.try` is often used to chain functions that can fail (as in the example above), returning the first error if any occurs. There is [a discussion](https://github.com/roc-lang/roc/issues/6828) to add syntax sugar for such chaining.
+`Result.try` is often used to chain two functions that return `Result` (as in the example above). This prevents you from needing to add error handling code at every intermediate step.
+
+<details>
+  <summary>Upcoming feature</summary>
+
+  We plan to introduce syntax sugar to make `Result.try` nicer to use, follow [this issue](https://github.com/roc-lang/roc/issues/6828) for more.
+</details>
 
 ### [Walking the elements in a list](#walking-the-elements-in-a-list) {#walking-the-elements-in-a-list}
 
@@ -1596,7 +1606,7 @@ main =
     Stdout.line! "Hello, World!"
 ```
 
-The `Stdout.line` function takes a `Str` and writes it to [standard output](<https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>). (We'll discuss the `!` part later.) `Stdout.line` has this type:
+The `Stdout.line` function takes a `Str` and writes it to [standard output](<https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>), we'll [discuss the `!` part later](https://www.roc-lang.org/tutorial#the-!-suffix). `Stdout.line` has this type:
 
 ```roc
 Stdout.line : Str -> Task {} *