From 7d2d62519adf34fdbf66c5f9fd238e113d54b9fb Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Fri, 2 Aug 2024 18:40:26 +0200
Subject: [PATCH 1/3] tutorial improvements

Some follow-up on #6952.
---
 roc-for-elm-programmers.md |  2 +-
 www/content/tutorial.md    | 21 ++++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/roc-for-elm-programmers.md b/roc-for-elm-programmers.md
index 39242d9a5ad..86dc1c67029 100644
--- a/roc-for-elm-programmers.md
+++ b/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
diff --git a/www/content/tutorial.md b/www/content/tutorial.md
index c4ca87d5147..dfec9f12b18 100644
--- a/www/content/tutorial.md
+++ b/www/content/tutorial.md
@@ -820,18 +820,29 @@ 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"`
+Result.try (Str.toU64 "2") listGet
+
+listGet = U64 -> Result Str [OutOfBounds]
+listGet = \index ->
+    List.get ["a", "b", "c", "d"] index
+
+# Running returns `Ok "c"`
 
 # 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 +1607,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 {} *

From bb2bae4b8ebd7bd6d1db61b7b2666fb312275b16 Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Fri, 2 Aug 2024 18:44:02 +0200
Subject: [PATCH 2/3] correct backtick

---
 www/content/tutorial.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/www/content/tutorial.md b/www/content/tutorial.md
index dfec9f12b18..81fa684e9aa 100644
--- a/www/content/tutorial.md
+++ b/www/content/tutorial.md
@@ -831,7 +831,7 @@ listGet = \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 `listGet`` function
+#  - 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
 ```

From dd6e4b211be6bf179fc793008063710fe459d208 Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Sat, 3 Aug 2024 12:37:03 +0200
Subject: [PATCH 3/3] fix typo, move comment

Signed-off-by: Anton-4 <17049058+Anton-4@users.noreply.github.com>
---
 www/content/tutorial.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/www/content/tutorial.md b/www/content/tutorial.md
index 81fa684e9aa..37dfd1d8dea 100644
--- a/www/content/tutorial.md
+++ b/www/content/tutorial.md
@@ -820,14 +820,13 @@ Result.isOk (List.get ["a", "b", "c"] 1)
 ```
 
 ```roc
+# Running this will produce `Ok "c"`
 Result.try (Str.toU64 "2") listGet
 
-listGet = U64 -> Result Str [OutOfBounds]
+listGet : U64 -> Result Str [OutOfBounds]
 listGet = \index ->
     List.get ["a", "b", "c", "d"] index
 
-# Running returns `Ok "c"`
-
 # Notes:
 #  - `Str.toU64 "2"` parses the string "2" to the integer 2, and returns `Ok 2` (more on
 #    integer types later)