Updated for Codespaces and reordered summary exercises

vignettes/ai.qmd

@@ -20,6 +20,8 @@ No need for nearly as much testing.
 
 -->
 
+<!-- AR: How should we expect students to be using AI for these tutorials? Chat, CLI, Agents? Should this doc just be tool agnostic? -->
+
 
 ## Introduction
 
@@ -240,21 +242,25 @@ Always begin by having students set up a repo and a Quarto document to work in.
 ````{verbatim}
 ### Exercise 1
 
-You should already be in a repo named `XX`. If not, create a that repo on GitHub and connect to wherever you are working. 
+Create a new repo using `codespace-starter` as a template and name it `r4ds-1`.
+
+If you haven't already, open the `r4ds-1` repo on GitHub and create a Codespace from it.
+
+You need two R Terminals: one for running this tutorial and one for your exercises.
 
-You need two R Terminals: this one for running the tutorial and one for writing your code and interacting with R.
+Create a new Quarto Document and save it as `analysis.qmd`. Add a YAML header at the top with a title (`"Analyzing the Billboard 100"`) and your name as author. 
 
-Create a new Quarto document. Provide a title -- `"XX"` -- and an author (you). Save the file as `analysis.qmd`. Render the document. 
+Render the document by running `quarto render` in the bash Terminal. Open the rendered `analysis.html` file in a new tab by right clicking it in the File Explorer and selecting "Open with Live Server". When you run `quarto render` from now on that tab will be updated with the newly rendered file.
 
 Create a `.gitignore` file with `analysis_files` on the first line and then a blank line. Save and push.
 
-In the Console, run:
+In the R Terminal, run:
 
 ```         
 show_file(".gitignore")
 ```
 
-If that fails, it is probably because you have not yet loaded `library(tutorial.helpers)` in the Console.
+If that fails, it is probably because you have not yet loaded `library(tutorial.helpers)` in the R Terminal.
 
 CP/CR.
 
@@ -285,16 +291,16 @@ The second question in the Introduction is usually:
 ````{verbatim}
 ### Exercise 2
 
-In your QMD, put `library(tidyverse)` in a new code chunk. Render the file using `Cmd/Ctrl + Shift + K`.
+In your QMD, put `library(tidyverse)` in a new code chunk. Render the file by running `quarto render` in the bash Terminal.
 
-Notice that the file does not look good because the code is visible and there are annoying messages. To take care of this, add `#| echo: false` to remove all the messages in this setup chunk. Also, add the following to the YAML header to remove all code echoes from the HTML:
+Notice that the file does not look good because the code is visible and there are annoying messages. To take care of this, add `#| message: false` to remove all the messages in this setup chunk. Also, add the following to the YAML header to remove all code echoes from the HTML:
 
 ```         
 execute: 
   echo: false
 ```
 
-Using `Cmd/Ctrl + Shift + K`, render the file again. Only the title and author should appear in the HTML.
+Render the file again, using `quarto render`. Only the title and author should appear in the HTML.
 
 In the Console, run:
 
@@ -439,7 +445,10 @@ The meat of a Topic generally involves asking AI to create a pipe which accompli
 
 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 . . . -->
+<!-- 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: I'm not sure what is meant by this comment.
+-->
 
 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.
 
@@ -448,7 +457,7 @@ Consider this example:
 ````{verbatim}
 ### Exercise 6
 
-Using your favorite AI, prompt it to generate R code that ... Add the code to your QMD in a new chunk. Place your cursor on the first line of the code and run `Cmd/Ctrl + Enter`.
+Prompt AI to generate R code that ... Add the code to your QMD in a new chunk. Place your cursor on the first line of the code and run `Cmd/Ctrl + Enter`.
 
 In the Console, run:
 
@@ -482,17 +491,10 @@ With `echo = FALSE` (the default), students see only the output of the chunk —
 
 ## Plotting Questions
 
-<!-- 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? 
-
-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. 
 
+<!-- AR: This seems like a reasonable place to keep code. So students can be totally sure and copy and paste if lost. -->
+
 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()`.
 
 
@@ -538,7 +540,7 @@ The second question tells the student to, in the QMD, assign the result of the p
 
 Within the latest code chunk, add the option: `#| cache: true`. Assign the result of the pipe to `x`. 
 
-`Cmd/Ctrl + Shift + K`. By including `#| cache: true` you cause Quarto to cache the results of the chunk. The next time you render your QMD, as long as you have not changed the code, Quarto will just load up the saved object.
+Run `quarto render` in the bash Terminal. By including `#| cache: true` you cause Quarto to cache the results of the chunk. The next time you render your QMD, as long as you have not changed the code, Quarto will just load up the saved object.
 
 If you have not done so already, you should add `analysis_cache` to the `.gitginore`. The content of the cache file does not belong on GitHub.
 
@@ -595,22 +597,20 @@ Our result:
 <!-- XX: Insert a knowledge drop related to this project. -->
 ````
 
-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: How relevant is this below paragraph given how students are using AI? -->
 
-<!-- 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. -->
+This also reminds students that they will often need to tell AI the variables in `x`, if they are using a chat interface, most easily by just copy/pasting the top of `x`.
 
 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.
+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.
 
 ````{verbatim}
 ### Exercise 6
 
-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.
+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`. If using a chat interface 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.
 
-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.
+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 `quarto render` to ensure that everything works. Make your plot look nice.
 
 In the Console, run:
 
@@ -642,6 +642,8 @@ Our result:
 <!-- XX: Insert a knowledge drop related to this project. -->
 ````
 
+Create a few exercises where students iteratively improve a plot. Perhaps adding features and themes. Since students are using AI to generate plots, they can make more of them. They need lots of practice evaluating and improving AI outputs.
+
 ## Tutorial Summary
 
 Once you have completed one or two Topics, it is time for the Summary section.
@@ -658,7 +660,7 @@ The last three questions are fairly self-explanatory.
 ````{verbatim}
 ### Exercise 1
 
-`Cmd/Ctrl + Shift + K` to ensure that everything works.  The resulting HTML page should be attractive, showing clean versions of your plot(s).
+Run `quarto render` to ensure that everything works.  The resulting HTML page should be attractive, showing clean versions of your plot(s).
 
 At the Console, run:
 
@@ -686,41 +688,42 @@ question_text(NULL,
 ````{verbatim}
 ### Exercise 2
 
-Commit and push all your files. Copy/paste the URL to your Github repo.
+Publish your rendered QMD to GitHub Pages. In the Terminal --- not the Console! --- run:
+
+```
+quarto publish gh-pages analysis.qmd
+```
+
+Copy/paste the resulting URL below.
 
 ```{r summary-2}
 question_text(NULL,
 	answer(NULL, correct = TRUE),
 	allow_retry = TRUE,
 	try_again_button = "Edit Answer",
 	incorrect = NULL,
-	rows = 3)
+	rows = 1)
 ```
 
 ### 
 
 <!-- XX: Insert a knowledge drop related to this project. -->
+
 ````
 
 
 ````{verbatim}
 ### Exercise 3
 
-Publish your rendered QMD to GitHub Pages. In the Terminal --- not the Console! --- run:
-
-```
-quarto publish gh-pages analysis.qmd
-```
-
-Copy/paste the resulting URL below.
+Commit and push all your files. Copy/paste the URL to your Github repo.
 
 ```{r summary-3}
 question_text(NULL,
 	answer(NULL, correct = TRUE),
 	allow_retry = TRUE,
 	try_again_button = "Edit Answer",
 	incorrect = NULL,
-	rows = 1)
+	rows = 3)
 ```
 
 ###