From 6d6a700092be76f4577cee17c22b749b9927dbc3 Mon Sep 17 00:00:00 2001
From: ptweeet <acrogers362@gmail.com>
Date: Wed, 13 May 2026 14:34:19 -0400
Subject: [PATCH 1/2] remove echo from questions. Add edit comments.

---
 vignettes/ai.qmd | 89 ++++++++++++++++++++++++++++--------------------
 1 file changed, 53 insertions(+), 36 deletions(-)

diff --git a/vignettes/ai.qmd b/vignettes/ai.qmd
index 0100c4e..dc992cf 100644
--- a/vignettes/ai.qmd
+++ b/vignettes/ai.qmd
@@ -12,7 +12,7 @@ vignette: >
 
 Rarely show students code. No one looks at code anymore.
 
-Most questions ask students to ask AI to do one of two things. Calculate some summary statistics or make a plot. (Often these are combined. Make a plot of summary statistics.) This is how we do data science with AI. We need to practice checking, not coding. Our job is to make sure that the AI has not made a mistake or, more commonly, than we have not misunderstood the data.
+Most questions ask students to ask AI to do one of two things. Calculate some summary statistics or make a plot. (Often these are combined. Make a plot of summary statistics.) This is how we do data science with AI. We need to practice checking, not coding. Our job is to make sure that the AI has not made a mistake or, more commonly, that we have not misunderstood the data.
 
 And, after they hit Continue, show (calculate on the fly) the summary statistics or show the plot. (But not the code that does this. Then SAY SOMETHING EDUCATIONAL, something that AI does not know, something that you might say to a student whose shoulder you are looking over.)
 
@@ -20,13 +20,17 @@ No need for nearly as much testing.
 
 -->
 
+<!-- AR: When it comes to creating summary statistics and plots should we motivate this with something? Questions, for example: What's the relationship between these two variables? What's the distribution of values of some variable across different categories of another. 
+
+In a lot of r4ds tutorials, we have a data set that we're from which we create a visualization. I feel like providing some more framing or motivation helps with giving students more of a sense of how / what to check. -->
+
 
 
 ## Introduction
 
 AI changes everything.
 
-This document describes the best way to write R tutorials using the [**learnr**](https://rstudio.github.io/learnr/) package. Prior to the rise of AI, [this](https://web.archive.org/web/20251008195459/https://ppbds.github.io/tutorial.helpers/articles/instructions.html) [was](https://web.archive.org/web/20251008195807/https://ppbds.github.io/tutorial.helpers/articles/books.html) the best way to write tutorials. Our purpose is no longer to teach students how to code. 
+This document describes the best way to write R tutorials using the [**learnr**](https://rstudio.github.io/learnr/) package. Prior to the rise of AI, this was the best way to write [tutorials](https://web.archive.org/web/20251008195459/https://ppbds.github.io/tutorial.helpers/articles/instructions.html) and [books](https://web.archive.org/web/20251008195807/https://ppbds.github.io/tutorial.helpers/articles/books.html). Our purpose is no longer to teach students how to code. 
 
 > *Our purpose is to teach students how to use AI to create.* 
 
@@ -112,7 +116,7 @@ question_text(NULL,
 
 ###
 
-```{r exercise-7-test, echo = TRUE}
+```{r exercise-7-test}
 
 ```
 
@@ -120,7 +124,7 @@ question_text(NULL,
 
 ````
 
-The question will almost always instruct the student to "CP/CR," often after running `show_fle(chunk = "Last")`. Adjust the value of `rows` to match the expected length of the pasted output. If the question asks student to run some R code, we will generally include a reasonable answer in the `test` chunk. This serves two purposes. First, because `echo = TRUE`, we show the student that code (and its output) in the tutorial. This code should be excellent. We want students to learn from our example. Second, the code will be run when we test the tutorial, so we can be sure that this code (and, we hope, code like it) will work for the student.
+The question will almost always instruct the student to "CP/CR," often after running `show_file(chunk = "Last")`. Adjust the value of `rows` to match the expected length of the pasted output. If the question asks the student to run some R code, include that code in the `test` chunk. It runs when we test the tutorial, ensuring correctness. Its output — a printed tibble, summary statistics, or plot — is shown to students after they click Continue, giving them something concrete to check their work against. We do not use `echo = TRUE` because, in the age of AI, we rarely want to show students code.
 
 ### Knowledge drops
 
@@ -159,9 +163,9 @@ The first two commands download data and save it to an RDS file in the `data` di
 
 This code assumes that you are located in the same directory as the `tutorial.Rmd` file. You only run those commands once, and then you comment them out because you don't want them re-run each time the tutorial is created. The `read_rds()` call is never commented out because we always need the `median_age` object.
 
-<!-- DK: Now, we don't show the "testing" code. We just show the result. -->
+<!-- DK: Now, we don't show the "testing" code. We just show the result. AR: Done. -->
 
-When designing tutorials which use objects like `median_age`, we generally write two code chunks. The first has the student run the same code as that which we used to create the object ourselves. This won't work if the student is not connected to the web but, with luck, in that case they will get a sensible error message. The second question informs the students that we have, behind the scenes, assigned the result of the function to an R object. We then ask the student to just print out that object. We don't have them do the assignment themselves, not least because we don't like questions which don't generate any output. 
+When designing tutorials which use objects like `median_age`, we generally write two questions. The first has the student run the download code themselves. The second informs students that we have, behind the scenes, already assigned the result to an R object, and asks them to print that object. We don't have them do the assignment themselves, since we prefer questions that generate visible output. The test chunk then shows that printed output — not the code — so students can check their result against ours.
 
 We use a similar approach with models which can take awhile to fit. Example:
 
@@ -438,18 +442,31 @@ question_text(NULL,
 <!-- XX: Insert a knowledge drop related to this project. -->
 ````
 
+<!-- AR: How do we set a goal for a topic?
+
+In many tutorials it seems like we highlight skills to learn, like downloading data and using parquet, in the first paragraph. Here, the data set is also introduced. In the next paragraph, we highlight certain functions to be used / learned.
+
+Should the goal be to answer some sort of question, using these skills? Seems more motivating to me.
+
+ -->
+
 The meat of a Topic generally involves asking AI to create a pipe which accomplishes some goal. The end of a Topic always finishes up with a plot. The last four questions set up and then guide the student to creating that plot. If you want the student to mimic a plot, you can place it in the `images` subdirectory and then use `knitr::include_graphics("images/plot.png")` to show it to students.
 
 To teach students about topic X, we first need to decide the final destination. What do we want students to be able to do on their own after completing the tutorial? For us, this will almost always be a plot. Having envisioned this goal, we need to create a "path" which students can use to reach that goal, first under our supervision and, second, on their own. The path will consist of several stepping stones, or stops along the way.
 
 <!-- DK: We should insert some discussion about creating a bunch of different pipes. The below is an OK start for this discussion. Add a code example . . . -->
 
-<!-- AR: Below, what is meant by "show students"? DK: Delete the below. Replace with: We don't show students our code because, in the age of AI, professionals don't look at code very often. -->
+<!-- AR: Below, what is meant by "show students"? DK: Delete the below. Replace with: We don't show students our code because, in the age of AI, professionals don't look at code very often. 
 
-To ensure that students are on the right path with their code, we need to provide them with our code that is verified to be correct. Although we should not tell students to replace their code with ours at every step, if a student is lost, they should be able to refer to our code to get back on track. We also want to include our code in test chunks, both to show students and to confirm that it works. 
+AR: No longer showing code to create outputs, just the outputs. -->
+
+We don't show students our code because, in the age of AI, professionals don't look at code very often. Instead, we show students the *result* — a plot or summary statistics — produced by our correct code. This gives students something concrete to check their AI-generated work against.
 
 Consider this example:
 
+<!-- AR: Would it be helpful to include text after the plot / summary statistic output but before the knowledge drop, that highlights certain checks a student should do to make sure that their output is good enough and that they should continue the conversation with AI to get a better result? -->
+
+
 ````{verbatim}
 ### Exercise 6
 
@@ -474,8 +491,8 @@ question_text(NULL,
 
 ###
 
-```{r, echo = TRUE}
-XX: Insert our excellent code, probably made with the help of AI but also "cleaned up" so that it is concise and provides an excellent example for students to mimic.
+```{r}
+# XX: Insert code that produces the correct result — a plot, summary statistics, or printed tibble. With echo = FALSE (the default), students see only the output, not this code.
 ```
 
 ### 
@@ -483,33 +500,29 @@ XX: Insert our excellent code, probably made with the help of AI but also "clean
 <!-- XX: Insert a knowledge drop related to this project. -->
 ````
 
-The R chunk with `echo = TRUE` allows the students to see the code we have written within it. This makes it easy for the students to copy and paste our code if they need to. 
+With `echo = FALSE` (the default), students see only the output of the chunk — a plot, printed tibble, or other result — not the code itself. If there is no meaningful output to show, omit the test chunk or set `eval = FALSE` explicitly.
 
-Since `eval = TRUE` is the default argument in an R chunk, the code within will automatically be run as well. Students will be able to see any output from the code, which can be helpful if the code plots a graph. If it is inappropriate or unnecessary to include the output of the code, just set `eval = FALSE` explicitly.
+## Plotting Questions
 
-In that case, the answer chunk would look like:
+<!-- AR: Should the cleaned data be checked once per topic, or every time before each plotting / summary stats questions? 
 
-````{verbatim}
-```{r, echo = TRUE, eval = FALSE}
-
-```
-````
+If once per topic, then move this into the Topics section? -->
 
-## Plotting Questions
+<!-- AR: How many plotting / summary stats questions to ask?  -->
 
 Plotting exercises are generally handled with a sequence of four questions. Prior to these, the tutorial will probably have the student practice gathering, organizing, and cleaning the data. 
 
-The first of the three prior questions tells the student to replace the current pipe which they have in the QMD with our code. We check that they have done so with `show_file()`. The purpose of this question is to ensure that the student's data will match our data.
+The first of the three prior questions ensures that the student's data matches ours. We show our result — the printed tibble — in a test chunk, and ask students to run their own pipe and compare. We check their code with `show_file()`.
 
 
 ````{verbatim}
 ### Exercise 3
 
-Before creating a plot, we need to ensure that your data matches our data. In the QMD, replace your code from the previous exercise with our code.
+Before creating a plot, we need to ensure that your data matches ours. Run your pipe in the Console and compare your output to the result shown below.
 
 In the Console, run:
 
-```         
+```
 show_file("analysis.qmd", chunk = "Last")
 ```
 
@@ -526,6 +539,12 @@ question_text(NULL,
 
 ###
 
+```{r xx-first-section-use-sentence-case-3-test}
+# XX: Insert code that prints the tibble students should have at this stage.
+```
+
+###
+
 <!-- XX: Insert a knowledge drop related to this project. -->
 ````
 
@@ -555,13 +574,7 @@ question_text(NULL,
     rows = 8)
 ```
 
-###
-
-Our code:
-
-```{r, echo = TRUE}
-# x <- ... where the ellipsis are replaced with the code which creates x.
-```
+<!-- AR: In previous question, show table output. Is there anything else to test here? -->
 
 ###
 
@@ -590,9 +603,9 @@ question_text(NULL,
 
 ###
 
-Our code:
+Our result:
 
-```{r, echo=TRUE}
+```{r}
 # x
 ```
 
@@ -603,6 +616,10 @@ Our code:
 
 This also reminds students that they will often need to tell AI the variables in `x`, most easily by just copy/pasting the top of `x` into the AI interface.
 
+<!-- AR: Combine questions 4 (cache tibble and save to `x`) and 5 (view `x`, compare with that in tutorial) below maybe also with 3 (compare working tibble to one in tutorial) above? Fewer knowledge drops, but then it's a single, verifiable question: Did you make the correct tibble and assign it to x? The test is whether x is the correct tibble.
+
+Replace with more plots and summary stats questions? Could create twice as many plots in the same number of questions. -->
+
 Could these questions be combined into one? Probably. But spreading things has two advantages. First, it ensures that even the weaker students do not get lost. Second, it provides us with more opportunities to drop some knowledge. 
 
 Now, we can move on to the plotting question. In the age of AI, students will have AI write code for their plot. They will do that while specifying that their data is `x` from earlier. The student will add their new code to a new code cell, and we check that they have done so with `show_file()`. The purpose of this question is to ensure that the student has generated their own code, albeit with AI help.
@@ -610,9 +627,9 @@ Now, we can move on to the plotting question. In the age of AI, students will ha
 ````{verbatim}
 ### Exercise 6
 
-Ask AI to generate R code that uses `x` to plot a basic graph showing XX ... Mention you want to use the data from `x` and copy/paste the `x` you ran in the Console with the resulting tibble. You only need the top 3 lines, mainly to include column names.
+Ask AI to generate R code that uses `x` to plot a basic graph or calculate and present summary statistics showing XX ... Mention you want to use the data from `x` and copy/paste the `x` you ran in the Console with the resulting tibble. You only need the top 3 lines, mainly to include column names.
 
-Within `labs()`, edit or add a proper title, subtitle, and caption. If axis labels would be useful, add them, but if unnecessary, don't bother. Don't assign the code for the plot to any variable. Put the plot code in a new code chunk. Run `Cmd/Ctrl + Shift + K` to ensure that everything works. Make your plot look nice.
+Consider adding a title, subtitle, and caption. If axis labels would be useful, add them, but if unnecessary, don't bother. Don't assign the code for the plot to any variable. Put the plot code in a new code chunk. Run `Cmd/Ctrl + Shift + K` to ensure that everything works. Make your plot look nice.
 
 In the Console, run:
 
@@ -633,10 +650,10 @@ question_text(NULL,
 
 ###
 
-Our code:
+Our result:
 
-```{r, echo=TRUE}
-# XX: Make sure your plotting code is good! This will take some time. You had better have a subtitle which provides the take-away message of the plot. AI sometimes gives you too much code, lots of `theme()` stuff and so on. This is no good! In most cases, we are happy with concise, straightforward code. 
+```{r}
+# XX: Insert plotting code. With echo = FALSE (the default), students see only the plot, not this code. Make sure the plot has a subtitle that states the take-away message and uses clean, concise code.
 ```
 
 ###

From 4caff45d8fcb6d6e26de4541a792345cfe8c9a6a Mon Sep 17 00:00:00 2001
From: ptweeet <acrogers362@gmail.com>
Date: Wed, 13 May 2026 15:44:42 -0400
Subject: [PATCH 2/2] updated exercise wording and comment

---
 vignettes/ai.qmd | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/vignettes/ai.qmd b/vignettes/ai.qmd
index dc992cf..3fb616f 100644
--- a/vignettes/ai.qmd
+++ b/vignettes/ai.qmd
@@ -506,13 +506,16 @@ With `echo = FALSE` (the default), students see only the output of the chunk —
 
 <!-- AR: Should the cleaned data be checked once per topic, or every time before each plotting / summary stats questions? 
 
-If once per topic, then move this into the Topics section? -->
+If once per topic, then move this into the Topics section? 
+
+How do we check to make sure their data manipulation is correct? Look at code? Table? Plots? Need to do that here?
+-->
 
 <!-- AR: How many plotting / summary stats questions to ask?  -->
 
 Plotting exercises are generally handled with a sequence of four questions. Prior to these, the tutorial will probably have the student practice gathering, organizing, and cleaning the data. 
 
-The first of the three prior questions ensures that the student's data matches ours. We show our result — the printed tibble — in a test chunk, and ask students to run their own pipe and compare. We check their code with `show_file()`.
+The first of the three prior questions ensures that the student's data matches ours. We show our result — the printed code that produces our tibble — in a test chunk, and ask students to copy and paste their own pipe and compare. We check their code with `show_file()`.
 
 
 ````{verbatim}